NSO20 StudentGuide PDF

NSO
Cisco Network Services

Orchestrator
Student Guide
DISCLAIMER WARRANTY: THIS CONTENT IS BEING PROVIDED “AS IS.” CISCO MAKES AND YOU RECEIVE NO WARRANTIES IN
CONNECTION WITH THE CONTENT PROVIDED HEREUNDER, EXPRESS, IMPLIED, STATUTORY OR IN ANY OTHER PROVISION OF
THIS CONTENT OR COMMUNICATION BETWEEN CISCO AND YOU. CISCO SPECIFICALLY DISCLAIMS ALL IMPLIED
WARRANTIES, INCLUDING WARRANTIES OF MERCHANTABILITY, NON-INFRINGEMENT AND FITNESS FOR A PARTICULAR
PURPOSE, OR ARISING FROM A COURSE OF DEALING, USAGE OR TRADE PRACTICE. This learning product may contain early release
content, and while Cisco believes it to be accurate, it falls subject to the disclaimer above.
Table of Contents
Course Introduction……………………………………………...…1
Cisco NSO Overview…………...…………………………….…..1-0
Network Orchestration Overview .......................................................... 1-1
Need for Network Orchestration ....................................................................................... 1-2
Network Management Challenges ................................................................................... 1-5
Business Implications .................................................................................................... 1-11
Orchestration Use Cases ............................................................................................... 1-17
Summary ....................................................................................................................... 1-33
Cisco NSO Architecture ..................................................................... 1-35
Cisco NSO Logical Architecture ..................................................................................... 1-36
Cisco NSO Components ................................................................................................ 1-42
Northbound APIs ........................................................................................................... 1-50
Packages ....................................................................................................................... 1-55
Network Element Drivers ............................................................................................... 1-58
Summary ....................................................................................................................... 1-68
NETCONF Overview ............................................................................ 1-69
Challenges of Network Management ............................................................................. 1-70
Introduction to NETCONF .............................................................................................. 1-79
NETCONF Operation ..................................................................................................... 1-88
Summary ....................................................................................................................... 1-97
YANG Overview ................................................................................. 1-99
Introduction to YANG ................................................................................................... 1-100
Other Representations of YANG .................................................................................. 1-108
YANG Data Types ....................................................................................................... 1-110
Basic YANG Statements .............................................................................................. 1-118
XPath Overview ........................................................................................................... 1-132
YANG Examples .......................................................................................................... 1-144
Summary ..................................................................................................................... 1-153
Start Using Cisco NSO.…………...…………………………......2-0

System Setup ....................................................................................... 2-1
Cisco NSO Setup Overview ............................................................................................. 2-2
Cisco NSO Local Installation ............................................................................................ 2-6
Cisco NSO System Installation ...................................................................................... 2-14
Installing NEDs .............................................................................................................. 2-19
Using Netsim ................................................................................................................. 2-27
Summary ....................................................................................................................... 2-32
Device Manager ................................................................................. 2-33
Overview........................................................................................................................ 2-34
Device Configuration Management ................................................................................ 2-38
Device Connection Management ................................................................................... 2-57
Templates and Groups .................................................................................................. 2-64
Other Device Magament Tools ...................................................................................... 2-72
Summary ....................................................................................................................... 2-82
Service Management.……...………………………………….….3-0
YANG Tutorial ........................................................................................ 3-1
Cisco NSO YANG Architecture ........................................................................................ 3-2
Creating a Service Package............................................................................................. 3-5
Cisco NSO CLI .............................................................................................................. 3-14
Service Template ........................................................................................................... 3-21
YANG Service Model ..................................................................................................... 3-25
Deploy a Service............................................................................................................ 3-37
Summary ....................................................................................................................... 3-40
FASTMAP..................................................................................................................... 3-41
Introduction .................................................................................................................... 3-42
Service and Device Models ........................................................................................... 3-45
FASTMAP Principles ..................................................................................................... 3-47
Advanced FASTMAP ..................................................................................................... 3-68
Summary ....................................................................................................................... 3-76
Service Design ................................................................................... 3-77
Service Design .............................................................................................................. 3-78
Service Design for Cisco NSO Top-Down Approach ...................................................... 3-85
Service Design for Cisco NSO Bottom-Up Approach ..................................................... 3-90
Device Configuration ..................................................................................................... 3-99
Service Model .............................................................................................................. 3-108
Summary ..................................................................................................................... 3-115
Service Management ........................................................................ 3-117
Service Management Tasks ........................................................................................ 3-118
Service Lifecycle Management Guidelines................................................................... 3-125
Summary ..................................................................................................................... 3-131
System Administration and Integration……………………..….4-0

Cisco NSO Integration Options ............................................................. 4-1
Cisco NSO Integration Options ........................................................................................ 4-2
Cisco NSO NETCONF API .............................................................................................. 4-4
Cisco NSO CLI API .......................................................................................................... 4-7
Cisco NSO Web Integration ........................................................................................... 4-16
Cisco NSO Plugin Scripts .............................................................................................. 4-20
Cisco NSO SNMP.......................................................................................................... 4-26
ii Cisco Network Services Orchestrator (NSO) 2.0 © 2016 Cisco Systems, Inc.
Summary ....................................................................................................................... 4-28
Cisco NSO System Administration ..................................................... 4-29
System Configuration..................................................................................................... 4-30
System Maintenance ..................................................................................................... 4-36
Authentication and Authorization.................................................................................... 4-42
High Availability ............................................................................................................. 4-46
Clustering ...................................................................................................................... 4-50
Scalable System Management ...................................................................................... 4-59
System Troubleshooting ................................................................................................ 4-74
Summary ....................................................................................................................... 4-81
Alarm Management and Reporting ..................................................... 4-83
Alarms Overview ............................................................................................................ 4-84
Alarm Management........................................................................................................ 4-59
Compliance Reporting ................................................................................................... 4-94
Summary ..................................................................................................................... 4-100
© 2016 Cisco Systems, Inc. Cisco Network Services Orchestrator (NSO) 2.0 iii
iv Cisco Network Services Orchestrator (NSO) 2.0 © 2016 Cisco Systems, Inc.
NSO
Course Introduction
Overview
Automation has been identified as one of the main areas where service providers and large enterprises can
reduce cost, which is becoming more and more important in today's business where average return per user is
diminishing year by year. Service Defined Network principles deliver abstractions of existing network
infrastructure, which enable faster service development and deployment. Standards like NETCONF and
YANG are currently the driving force behind those abstractions and are proposing a significant improvement
to network management.
The Cisco Basic NSO course introduces Cisco Network Services Orchestrator solution which leverages the
power of YANG and NETCONF to streamline network operations and management. By focusing on latest
standards and innovation, Cisco NSO is a true multivendor SDN solution.
2 Cisco Network Services Orchestrator (NSO) 2.0 © 2016 Cisco Systems, Inc.
Lesson 1-1
Network Orchestration
Overview
Overview
This lesson provides an overview of network orchestration.
Objectives
Upon completing this lesson, you will be able to meet these objectives:
 Explain why a network orchestration layer is required
 Describe the legacy network management issues
 Describe the business implications of network orchestration
Need for Network Orchestration
This topic illustrates the need for network orchestration.
Business Challenge
 Network operators and service

providers are seeing high costs of
network operations Costs
 It takes time to introduce new services
 It takes time to deploy service
instances to customers
Revenue
 Provisioning is often hard-coded
 Network adapters are expensive and
rigid
© 2016 Cisco and/or its affiliates. All rights reserved. Cisco Network Services Orchestrator 4
Network operators and service providers today are struggling to control the difference between the growth of
their operating costs and their revenue. While the revenue from new services seems to be growing slower,
their operating costs seem to be growing faster and their operating complexity grows with each new services.
This makes introduction and deployment of new services much slower compared to service demand and
availability on the market. The main reason for this are inadequate provisioning processes where services are
either configured manually or hard-coded inside the Operations Support Systems (OSS). To make things
worse, adapters to network devices are often expensive and hard to maintain. The adapters used between the
OSS and the network devices are proprietary and usually translate the OSS logic to the device CLI. Adapters
take time to develop and new features need to be added with new versions of device firmware. The support
for these new features has to be incorporated into the network adapters and these upgrades and maintenance
of network adapters is usually expensive.
1-2 Cisco Network Services Orchestrator (NSO) 2.0 © 2016 Cisco Systems, Inc.
SDN and NFV Approach
 SDN and NFV address these challenges

 SDN and NFV enable near real-time OSS
 SND and NFV make instant response possible
 Deploying SDN/NFV takes time:
 Requires organizational changes
 Requires network changes
 Requires OSS changes
 Requires change of business processes
Software-defined networking and network functions virtualization (SDN and NFV) promise to solve this
dilemma. However, deploying SDN and/or NFV requires extensive changes which touches the whole
organization. Deploying SDN/NFV requires changes to the network, from upgrading software, replacing
physical devices and changing network topology. Additionally, it disrupts operations and requires changes or
even replacement of existing OSS systems.SDN and NFV enables OSS systems to become almost real-time
which enables instant response to customer requests and instant service fulfilment. This makes new, more
flexible business models possible but also requires a change in the business processes.
© 2016 Cisco Systems, Inc. Cisco NSO Overview 1-3

Network Orchestration Layer
BSS/OSS
Service attributes
Network Orchestration
Layer
Device Configuration
An orchestration layer is proposed to achieve the benefits promised by SDN/NFV without overhauling the
network and disrupt operations and introduction of a network service.
Network Management Challenges
This topic describes network management issues.
 We are configuring individual devices

 There is no real network management or service management
 There is no abstract models beyond device level
 Networks are evolving much slower than for example software
The traditional network management approach is based upon managing separate devices. The industry is
rapidly moving towards a service-oriented approach to network management, where complex services are
supported by many different systems. To manage these, operators are starting a transition from managing
pieces of equipment towards a situation where an operator is actively managing the various aspects of
services.
In the past several years Software-Defined Networking (or SDN) has emerged as a solution. The basic idea is
to provide a centralized, unified set of APIs with which networks and services can be controlled by software
– automatically and in real time. The promised benefits include faster and more precise control of networks
and services leading to higher performance and lower costs.
Cisco NSO enables operators to dynamically adopt the service configuration solution according to changes in
the offered service portfolio. It delivers the SDN vision today in providing a logically centralized interface
towards the multi-vendor network. The network can be a mix of traditional equipment, virtual devices and
OpenFlow switches.

Network Management Challenges (Cont.)
Operations Problems
 Complexity barrier Order Management
 Scripting BSS/OSS
Inventory
 Limited portability Service Activation
 Limited standardization
Network Integration
 Not real time Ad-hoc
Configuring the services and the affected equipment are among the largest cost-drivers in provider networks.
Still, the common 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 of the
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.
Programmability Challenges
 Manual, per-device configuration
 Slow and error prone
 Lack of well defined network API
Order Service
Inventory
Management Activation
When compared to software, networks are much slower to evolve. Configuration is usually done manually on
each device which is a slow process and is prone to errors. There is no such thing as a network API so
operators are usually using scripting when trying to automate device configuration changes. Additionally,
there are no well-defined protocols or data models for network configuration and there is no such thing as an
atomic change. This leads to high complexity and possibility of errors when changing configuration.

Configuration changes (NMS)
Consistency Issues
NMS
NMS
 Many sources of configuration
 Change driven by individual network
engineers
 60-90% valid data
Configuration (script)
 Fire and forget approach
Configuration changes (CLI)

There are many sources of configuration changes. Several different engineers are changing configurations
over time. Some of them do it directly through CLI, others write scripts and some changes are even applied
through NMS systems. In a complex network with high amount of changes there is also a lack of strong
governance over network configuration. This leads to inconsistencies between local and centralized network
data and results in faults and provisioning delays. The most common approach is the so called “fire and
forget”.
Addressing Network Management Challenges
Cisco NSO Solution Management Network
Applications Engineer
 Multi-vendor service orchestration platform
NETCONF, REST,
 Multi-vendor service-layer SDN controller CLI, WebUI
Java, WS, Scripts
 Supports traditional L2-L7 networking,
virtual devices and OpenFlow
Cisco
 Provides a single API and single UI to
NSO
entire managed environment
 Keep accurate copy of network
configuration state
 Makes sure configuration is synchronized
with the network
Primarily, Cisco NSO is a multi-vendor service orchestration platform that enables End-to-End Service
Orchestration across physical or virtual devices. Cisco NSO can also be percieved as a multi-vendor service-
layer SDN controller for data centers and service providers. Along with traditional L2 – L7 networking it
also supports virtual devices and OpenFlow. Cisco NSO provides a single API and a single UI to the
network. Cisco NSO keeps an accurate copy of network configuration state at all times so the state of the
NSO database always mirrors the actual state of the network. Cisco NSO makes sure that the configuration
database is synchronized with the network devices at all times.

Cisco NSO Direction
 NETCONF as preferred device management YANG

Service
protocol Attributes Service
Models
 YANG for service and device modeling
Transparency boundary Cisco
 Make devices transparent to service NSO
management YANG
NETCONF Device
 Provide northbound service management APIs Models
Cisco or
 Reliable network configuration management ESC Device
Configurations
through network-wide transactions CLI NEDs
REST
 Network Element Drivers (NEDs) for
non─NETCONF elements
Virtual
 Elastic Services Controller (ESC) for VNFs Network
VNF VNF Physical Network
lifecycle management Environment
Environment
The two primary components of Cisco NSO are:

 NETCONF to enable standard and efficient automation of configuration management on network
devices.
 YANG to enable simple and efficient modeling of services and devices.
As a result, Cisco NSO can make devices transparent to service models thus simplifying service design,
deployment and maintenance. The FASTMAP algorithm further simplifies service design and also ensures
optimal and reliable configuration management.
While most network devices today do not (fully) support NETCONF, Cisco NSO can make use of Network
Element Drivers (NEDs) to model the native device’s CLI using YANG as well.
For solutions based on network function virtualization (NFV), Cisco Elastic Services Controller (ESC) can
be used to provide a NETCONF-enabled virtual machine manager (VMM) currently supporting OpenStack
and VMware environments.
Business Implications
This topic describes the business implications of implementing Cisco NSO.
Faster Service Deployment
 Rapid deployment of provisioning and configuration management systems

 Time-to-market improvements
 Reduction in product development time
 Trouble-free scaling of new networks and services
One of the main benefits of deploying Cisco NSO is faster service deployment and deployment of
configuration management systems. It also makes networks more scalable because new devices can be
added and configured with minimal effort. The same goes for device replacement – devices can be replaced
quickly with little to no additional configuration.

Productivity Improvements
 Faster introduction and activation of new services

 Trouble-free scaling of new networks and services
 Productivity improvements
 Automate network changes and service activation
 Avoid configuration errors
 Improved data quality used in planning and troubleshooting
Due to configuration consistency between the physical network and the configuration database configuration
errors can be avoided and the process of network planning and troubleshooting can be improved.
Transactional Management
Legacy Situation – No Transactions
 No well-defined protocols and data-models
 Lack of atomicity OSS
NMS
 Ordering problem EMS
NETCONF
Manager
 Result: high cost and complexity

Cost and
complexity
Legacy network management doesn‘t define any configuration management protocols and data models. The
closest thing to this is the SNMP protocol, which was never intended to manage configurations in the first
place. There are also no clearly defined data models that would describe device configuration and there is no
standardization among different device vendors. When a configuration set is pushed to the device the order
of individual configuration steps is very important and it means the difference between a successful or
unsuccessful application of the configuration. The ordering of the configuration steps is up to the engineer
writing the configuration. As a result, this configuration approach is very complex, doesn‘t scale well and is
therefore also very expensive.

Transactional Management (Cont.)
Transactional Model
 Network wide transactions
 Device, network and service models OSS
NMS
 Standardized protocols EMS
NETCONF
Manager
 Result: reduction in cost and

complexity Reduced Cost/
Cost and Value
Complexity
The network service orchestration layer distribute or program network configuration as a single atomic
transaction. A transaction is a set of configuration changes that need to be applied to a device. If there is any
failure in a transaction, the local configuration is supposed to be automatically rolled-back to the state of the
last "good" transaction. Even if a configuration of a single device fails, the entire service deployment can be
compromised. If the configurations that have already been applied are not rolled back completely, the
network is then left in an inconsistent state. Additionally, devices should be able to determine in what order
the individual steps should be applied. This reduces the configuration complexity and cost and increases
scalability.
Standards development
RFC 3535
 SNMP is not appropriate for
Abstract
configuration management
This document provides an overview of a
workshop held by the Internet Architecture  CLI scripting is proprietary,
Board (IAB) on Network Management. The expensive to maintain, often
workshop was hosted by CNRI in Reston, VA, unreliable
USA on June 4 thru June 6, 2002. The goal of
the workshop was to continue the important  “Market share” 70%+
dialog started between network operators and
protocol developers, and to guide the IETFs
focus on future work regarding network
management.
The SNMP management technology was created in the late 1980s and has since been widely implemented
and deployed in the Internet. There is lots of implementational and operational experience, and the
characteristics of the technology are thus well understood.
SNMP works reasonably well for device monitoring. The stateless nature of SNMP is useful for statistical
and status polling.
SNMP is widely deployed for basic monitoring.
There are many well defined proprietary MIB modules developed by network device vendors to support their
management products.
SNMP is an important data source for systems that do event correlation, alarm detection, and root cause
analysis. SNMP requires applications to be useful. SNMP was, from its early days, designed as a
programmatic interface between management applications and devices. As such, using SNMP without
management applications or smart tools appears to be more complicated. Standardized MIB modules often
lack writable MIB objects which can be used for configuration, and this leads to a situation where the
interesting writable objects exist in proprietary MIB modules.
There are scaling problems with regard to the number of objects in a device. While SNMP provides
reasonable performance for the retrieval of a small amount of data from many devices, it becomes rather
slow when retrieving large amounts of data (such as routing tables) from a few devices.
There is too little deployment of writable MIB modules. While there are some notable exceptions in areas,
such as cable modems where writable MIB modules are essential, it appears that router equipment is usually
not fully configurable via SNMP.
The SNMP transactional model and the protocol constraints make it more complex to implement MIBs, as
compared to the implementation of commands of a command line interface interpreter. A logical operation
on a MIB can turn into a sequence of SNMP interactions.

Business Implications
OPEX Reduction
OPEX/CAPEX (per year) TCO for 5 years OPEX per task
OPEX CAPEX Other Configuration/
Activation
Change
mgmt.
Fault
management
CAPEX OPEX is often 45% of OPEX

decreases over around 80% is typically
the years of 5 years Configuration &
OPEX does not TCO Activation
Source: Nokia Solutions

When we look into operator‘s cost structure over a 5 year period, it is evident that capital expenditures
decrease over the years while the operational expenditures do not. Sometimes they even rise due to
implementation of new services. After 5 years, around 80% of the total network cost is due to operational
expenditures. When broken down into specific tasks, these amount to:
 Service configuration and activation: tasks required to configure and activate a certain service (for
example bandwidth on demand).
 Fault management: tasks required to recover from faulty configuration.
 Change management: tasks required because the service or service parameters have changed (for
example bandwidth on demand service requires additional access classes for IPTV).
 Other tasks.
Orchestration Use Cases
This topic describes some of the use cases for deploying Cisco NSO to enable end-to-end and
network-wide orchestration of services.
Orchestration Use Cases Using Cisco NSO
 Transport services (e.g. L2 & L3 MPLS VPNs)

 Managed services (e.g. managed CPE)
 Virtual Managed Services (vMS) using network function virtualization
(NFV) to implement managed network elements (e.g. vCPE, vFW)
 Virtual Packet Core (QvPC) with simple on-demand scaling of mobile
packet networking
 Resource management configuration
 Device management (e.g. configuration standardization and
compliance)
The following lists some of the possible use cases for Cisco NSO:
 Transport services such as those using Layer-2 or Layer-3 MPLS VPNs
 Managed services such as the Managed CPE service that may optionally also provide some self-service
capabilities to end users
 Virtual Managed Services (vMS) using network function virtualization (NFV) to implement managed
network elements (e.g. vCPE, vFW)
 Virtual Packet Core (QvPC) with simple on-demand scaling of mobile packet networking
 Resource management configuration such as self-service for the Bandwidth On demand service
 Device management such as configuration standardization and compliance enforcement and reporting

NSO Ecosystem and ETSI NFV MANO NFV Management
and Orchestration
(MANO)
Service Parameters
Cisco NFV Orchestrator

NSO (NFVO)
Cisco 3rd Party VNF Manager

ESC CTCM VNFM (VNFM)
Virtualized
Cisco Cisco 3rd Party
OpenStack VMware Infrastructure
APIC VTC VIM
Manager (VIM)
Virtual or
vFW vCPE vSLB vIPS vWSA vESA vISE Physical
AVS VTF OVS/DVS Infrastructure
Physical Network Infra. Virtual Network Infrastructure
The figure illustrates the ETSI Management and Orchestration (MANO) architecture used to enable a
Network Function Virtualization (NFV) service. The figure illustrates the following layers in the
architecture:
 The NFV Orchestrator (NFVO) layer where Cisco NSO can be deployed to orchestrate NFV services.
 The VNF Manager (VNFM) layer where Cisco Elastic Services Controller (ESC) can be deployed to
control the lifecycle of Virtual Network Functions (vNFs). Alternatively, any other 3rd party system can
be used to achieve a similar management goal.
 The Virtualized Infrastructure Manager (VIM) is used to manage the virtual and optionally also physical
infrastructure hosting and interconnecting the vNFs. The figure lists the following examples:
OpenStack, VMware, Cisco APIC (for Cisco ACI solutions), Cisco VTC (for Cisco VTS solutions), or
any other 3rd party systems.
 The last layer consists of the physical and virtual infrastructure that provides the end-functionality for
the designed NFV services such as physical and virtual network devices.
NSO Use Cases
Example: MPLS VPNs
MPLS
CE PE PE CE
Create Service
Instance
Web Cisco
Frontend NSO
 Network-wide end-to-end configuration of VPN service (L3, L2, VPLS)

 Optionally also including CPE equipment
The figure illustrates a traditional L2 or L3 MPLS VPN where Cisco NSO can be deployed to manage
provider edge routers (PEs) and optionally also the customer edge routers (CEs).
Additionally, the orchestrated solution would typically involve integration with a frontend portal (e.g.
existing OSS/BSS system or a custom made web portal) to simplify service management.

NSO Use Cases
Example: Managed CPE
Internet
CPE
Service Management
Web Cisco Day-0

Frontend NSO Server
 Simplified service instance deployment including zero-touch provisioning

 Optional self service (e.g. web-based firewall configuration)
The figure illustrates a solution where a managed CPE service is implemented to streamline the provisioning
and management of CPE devices. In addition to orchestrating the configuration of CPEs, a day-0 server can
be deployed to simplify the deployment of new CPEs with zero-touch provisioning.
NSO Use Cases
Example: Virtual Managed Services
MPLS
or Internet
IPsec over Internet vRTR vFW
CPE PE PE GW
Internal
User
vIPS
DC Remote
Access User
 NFV Service Packages consisting of a number of selected VNFs

 Service chains used to link individual components into an end-to-end
service
The figure illustrates the Virtual Managed Services (vMS) solution where the following components are
managed end to end:
 The transport network such as Layer-2, Layer-3 MPLS VPN, VPLS, IPsec VPN, etc., in order to
connect end-customer sites to the data center.
 The CPE devices
 The virtual network functions (vNFs)

NSO Use Cases
Example: Virtual Managed Services (Cont.)
MPLS
or Internet
CPE PE PE GW
Internal Day-0
User configuration
vIPS
DC Remote
Day-0 Server Access User
Cisco
 May include a Managed CPE service NSO
 New device registers with Day-0 server

 Day-0 server provides initial config for CPE and registers device in NSO
In order to streamline the deployment of the vMS service we should employ a day-0 server for zero-touch
provisioning of CPE devices. A new device will register with the day-0 server and retrieve the day-0 config
while the day-0 server will register the new device with Cisco NSO that will manage the CPE device for the
remainder of its lifecycle.
NSO Use Cases
MPLS
or Internet
CPE PE PE GW
Internal Day-0
User configuration
vIPS
Service Orchestration
DC Remote
Cisco
NSO
Cisco
 NSO Initiates VNF VM creation via ESC ESC
 NSO deploys service by configuring physical and virtual devices

The figure illustrates the next element in the solution where the Cisco Elastic Service Controller (ESC) is
used to manage the lifecycle of virtual machines used to implement virtual network functions (vNFs).

NSO Use Cases
MPLS
or Internet
CPE PE PE GW
Internal Day-0
User configuration
vIPS
Service Orchestration
DC Remote
Cisco
Web NSO
Frontend(s) Cisco
and ESC
OSS/BSS
The figure illustrates different levels of access to the solution:

 A dedicated web portal can be deployed to provide self-service to end users.
 Cisco NSO can also be integrated with existing OSS/BSS systems to accommodate the provisioning and
management of service instances.
 Direct access to Cisco NSO via the CLI or WebUI can be used for system maintenance and
troubleshooting tasks.
Cisco Elastic Service Controller (ESC) Overview
 VNF lifecycle management VNF Recovery and

Elasticity
 VNF day-0 configuration
Agentless, Multi- Intelligent Rules
 VNF license management vendor VNFs based Engine
 VM and service monitoring, recovery

and elasticity End to end VNFD driven,
Customization for Faster Programmable and
Innovations Extensible
 Transaction resume and rollback VNF deployment
Agility and Optimal Capacity
 Coupled VM VNF management (VM management
affinity, startup order, manage VM
interdependency)
Cisco Elastic Services Controller (ESC) is a Virtual Network Functions Manager (VNFM) and it performs
life cycle management of Virtual Network Functions (VNFs). ESC provides agentless and multi vendor VNF
management by provisioning the virtual services and monitoring their health and promotes agility, flexibility,
and programmability in Network Function Virtualization (NFV) environments. It provides the flexibility to
define rules for monitoring, and associate actions that are triggered based on the outcome of these rules.
Based on the monitoring results, ESC performs scale in or scale out operations on the VNFs. In the event of a
VM failure ESC also supports automatic VM recovery.
ESC fully integrates with Cisco and other third party applications. As a standalone product, the ESC can be
deployed as a VNF Manager. ESC integrates with Cisco Network Services Orchestrator (NSO) to provide
VNF management along with orchestration. ESC as a VNF Manager targets the virtually managed services
and all service provider NFV deployments such as virtual video, WiFi, authentication and so on. Complex
services include multiple VMs that are orchestrated as a single service with dependencies between them.
These multiple VMs are managed as a single entity, such as, Virtually Managed Services (vMS) 1.0 and
later.
Key Features of Elastic Services Controller
 Provides open and modular architecture, which allows multi-vendor OSS, VNF and VIM support.
 Provides end-to-end dynamic provisioning and monitoring of virtualized services using a single point of
configuration.
 Provides customization across different phases of life cycle management; while monitoring the VM,
service advertisement, and custom actions.
 Provides agentless monitoring with an integrated Monitoring Actions (MONA) engine. The monitoring
engine provides simple and complex rules, to decide scale in and scale out of VMs.
 Provides scale in and scale out options based on the load of the network.
 Deploys or removes VMs based on the monitoring errors and threshold conditions detected as part of
healing (also called as recovery).
 Supports service agility by providing faster VNF deployment and life cycle management.

 Supports multi-tenant environments.
 Supports REST and NETCONF / YANG interfaces to provide better hierarchical configuration and data
modularity.
Cisco ESC Architecture NETCONF Cisco
1. NSO
ESC
API Module ConfD Module Service Monitoring, Elasticity and
Advertising 2.
Southbound
YANG
programming Service Rules Advertising
Model
Monitor Engine Engine
VM Provisioning Service Configuration
Module Module
VIM / Cloud Integration
Other actions
Native Day-0 Monitor
VIM API Config VM
OpenStack NETCONF, CLI, REST, ...

or
VMware vRTR vFW
ESC Architecture
Cisco Elastic Services Controller (ESC) is built as an open and modular architecture that allows OSS, and
multi-vendor support. It performs life cycle management of the VNFs, that is, VNF onboarding, configuring
the VNFs, monitoring them, and making VNF level life cycle decisions such as healing and scaling based on
the KPI requirements. ESC and its managed VNFs are deployed as VMs running within a Virtual
Infrastructure Manager (VIM). Currently, OpenStack and vCenter 5.5 are the supported VIMs. The ESC core
engine manages transactions, validations, policies, workflows, VM state machines and rollbacks. The
monitoring and actions service engine in ESC performs monitoring based on several monitoring methods.
Events are triggered based on the monitoring actions. The monitoring engine also supports custom
monitoring plugins.
ESC can be configured for High Availability.
ESC interacts with the top orchestration layer using the REST and NETCONF/YANG NB APIs. The
orchestration layer can be a Cisco NSO or any third party OSS. ConfD enables integration with NSO by
adding NETCONF/YANG northbound interface support. A configuration template, Virtual Network
Function Descriptor (VNFD) file is used to describe the deployment parameters and operational behaviors of
the VNFs. The VNFD file is used in the process of onboarding a VNF and managing the life cycle of a VNF
instance.

VNF Lifecycle Management – Monitoring & Elasticity
Elastic Services Controller
VNF VNF VNF
Analytic Engine Rule Engine
Provisioning Configuration Monitor
Provision Configure Verify VM Verify
VM Service Boot Status VM Status
Service Custom Script

Predefined Action
Overloaded/Underloaded Action
VM Custom Script
Predefined Action Action
VM Bootstrap VM Service Bootstrap Service Service Overloaded/Underloaded
process alive Process alive Functional Custom Script
Service DEAD Predefined Action
Action
Custom Script
VM DEAD Predefined Action
Action
Predefined Action Predefined Action
Custom Script Custom Script

Action Action
VNF Creation VNF Automated Management

The figure illustrates the initial VNF provisioning task and the ongoing VNF service instance monitoring and
management tasks.
VNF Lifecycle Management – Monitoring & Elasticity
List of Events List of Actions Simple Rules
 VM Alive  Notify (callback) Service Alive => advertise
 Service Alive  Advertise Service
 Upper load threshold  Withdraw Service VM Dead => withdraw
crossed  Restart VM Upper load => scale up
 Lower load threshold  Scale up (add a VM)
and/or
crossed  Scale down (remove
Complex Rules
 Service Dead a VM)
 VM Dead  Individually Service Alive => Advertise, Notify
customizable
Heavy load => Scale up, Notify, Advertise
action(s) for every
event Service Dead => Withdraw, Notify, Restart
 Rules control ESC behavior

 Rule triggered by event
 Rule triggers an action (simple rule) or multiple actions (complex rule)
Cisco Elastic Services Controller (ESC) provides a single point of control to manage all aspects of VNF
lifecycle for generic virtual network functions (VNFs) in a dynamic environment. It provides advanced VNF
life cycle management capabilities through an open, standards-based platform that conforms to the ETSI
VNF management and orchestration (MANO) reference architecture.
In ESC Release 2.0, you can orchestrate VNFs within a virtual infrastructure domain—either in an
OpenStack or ESXi 5.5 environment. A VNF deployment is initiated as a service request. The service request
comprises of templates that consist of XML payloads.
The figure explains the lifecycle management of ESC:
 Onboarding—In ESC, you can onboard any new VNF type as long as it meets the prerequisites for
supporting it in an OpenStack and VMware environment. For example in Openstack environment, Cisco
ESC supports QCOW2 image format and config drive support for the VNF bootstrap mechanism. You
can define the XML template for the new VNF type to onboard the VNF with ESC.
 Deploying—When a VNF is deployed, Cisco ESC applies "day-zero" configuration for a new service. A
typical configuration includes credentials, licensing, connectivity information (IP address, gateway), and
other static parameters to make the new virtual resource available to the system. It also activates licenses
for the new VNFs.
 Monitoring— ESC integrates with the host hypervisor, whether KVM/OpenStack or VMware, to
monitor the health of virtual machines. It tracks performance metrics such as CPU use, memory
consumption, and other core parameters. The requester can specify all of the characteristics (for
example, vCPU, memory, disk, monitoring KPIs, and more) typically associated with spinning up and
managing a virtual machine in an XML template. It also provides an elaborate framework to monitor
service performance-related metrics and other key parameters that you define.
 Healing—ESC heals the VNFs when there is a failure. The failure scenarios are configured in the KPI
section of the datamodel. ESC uses KPI to monitor the VM and the events are triggered based on the
KPI conditions. The actions to be taken for every event that is triggered is configured in the rules section
during the deployment.
 Updating— Starting from ESC Release 1.1 and onwards, ESC allows deployment updates during
deployment. You can either perform all the updates (that is, add or delete a vm_group, add or delete a

ephemeral network in a vm_group, and add or delete an interface in a vm_group) in a single deployment
or individually.
 Undeploy— ESC allows you to undeploy an already deployed VNF. This operation is either done using
the northbound APIs or through the ESC portal.
NSO Use Cases NFV MANO
Example: Quantum Virtual Packet Core (QvPC)

Cisco NSO
Network + Mobility Function Pack
NFV
Orchestrator
QvPC DI QvPC DI QvPC DI QvPC DI (NFVO)
Service Configuration
CF CF CF CF
QvPC SI Configure VM VNF Manager

(VNFM)
CTCM
QvPC DI QvPC DI QvPC DI QvPC DI
SF SF DC 2 SF SF Instantiate VM
Virtualized
DC 1 DC N OpenStack Infrastructure
or VMware Manager (VIM)
 Single or distributed instances of packet core elements Compute, Virtual or

Storage & Physical
 On-demand expansion of resources to meet demand Network Infrastructure
As the industry's most complete, fully virtualized evolved packet core, the new Cisco Virtualized Packet
Core (VPC) solution redefines the paradigm of agility for service providers.
Cisco's VPC combines all packet core services—for 4G, 3G, 2G, Wi-Fi, and small cell networks—into a
single solution. It provides those network functions as virtualized services, so you can scale capacity and
introduce new services much faster and more cost-effectively.
Cisco's VPC is the industry's first hardware platform and hypervisor-independent solution that combines
network functions virtualization (NfV) and software-defined networking (SDN). This functionality helps
service providers nimbly scale new packet core systems for markets such as automotive, energy, and
healthcare.
Cisco's VPC allows service providers to leave intact their existing Cisco ASR 5000 Series investments and
continue to scale them for consumer and enterprise services.
Cisco's VPC reduces the time for service providers to deploy new services and reduce your operational
expenditures.

NSO Use Cases
Example: Network Resource Management Using Cisco WAE
Reconfigure
MPLS Traffic Cisco
Engineering NSO
Network Trigger
Reconfiguration
Retrieve
Resource Cisco
WAE
Utilization Data
Analyze and
Optimize Paths
 Dynamic network resource management
The figure illustrates a use case where Cisco WAE is used to manage the MPLS Traffic Engineering paths to
optimize the utilization of the entire MPLS network.
Summary
This topic summarizes the key points that were discussed in this lesson.
 Legacy network management of today has several issues owing to the absence of abstract
models beyond the device level.
 Network operations suffer from configuration complexity and inconsistency which results
in high costs, slow network changes and high level of failure management.
 Network programmability today is slow and prone to errors. As a result, networks evolve
much slower compared to software.
 Introducing the transactional based approach reduces configuration complexity and cost.
 A Cisco NSO system speed up service development and deployment and reduce OPEX.
References
For additional information, refer to these resources:
 Cisco NSO documentation and manual pages

Lesson 1-2
Cisco NSO Architecture

Overview
The purpose of this lesson is to give an overview of Cisco Network Services Orchestrator
Architecture and outline individual components of Cisco NSO.
Objectives
 Describe the overall NSO Architecture
 Identify the different components of NSO and describe their role in the architecture
Cisco NSO Logical Architecture
This topic describes NSO Architecture.
The Power of Abstractions

 Networking currently lacks fundamental abstractions
 As a result, networks are hard to manage
 Abstractions simplify and speed up development
 SDN proposes global network view abstraction
The current state of networking lack the fundamental abstractions that are so commonly used for example in
software development. Abstractions reduce complexity and enable the developers to focus on the task on the
actual problem they are solving. Due to the lack of abstractions the networks have become hard or even
impossible to manage efficiently. The proposed abstraction for networking is a global network view.
Three-Layered Architecture
SDN Architecture Abstract Network View
Specification Layer (Service Layer) Control Program
Global Network View (abstraction)
Network Operating System Layer Network Operating System (e.g. NSO)
Device Control
Protocols Protocols Protocols

Forwarding Layer
Cisco NSO shares the three-layer management architecture with the Software Defined Networking (SDN)
solutions. SDN is mainly about splitting the Network Problem into more manageable pieces by defining
higher level abstractions. The proposed three-layered architecture consists of the specification, the network
operating system and the forwarding layer. The key here is that the network configuration is derived from the
global network state. It is also worth pointing out that SDN does not equal OpenFlow, which is only one of
the possible implementations for the forwarding layer. In reality, the forwarding layer is usually a mix of
non-OpenFlow and OpenFlow devices.
The Specification Layer (more commonly referred to as the Service Layer) provides an interface for
operators and applications:
 It hides the complexities of distributed systems (networks).
 Utilizes a model-to-model mapping taking high-level concepts to specific device objects. It uses
models to describe services. These models are mapped to device models which provides a full service to
device mapping.
 It is transactional in order to protect operators and applications from having to deal with the
complexities of error recovery and activation orchestration.
The Network Operating System Layer provides a device-level interface:

 It is transactional to protect from error recovery and activation orchestration complexity.
 It feeds a model-to-multiple protocols mapping where device type, vendor and management protocol
is irrelevant to operators and applications.
The Forwarding Layer can be controlled through OpenFlow or traditional protocols like Cisco CLI, Simple
Network Management Protocol (SNMP) etc:
 In reality this is a mix of traditional and OpenFlow devices.
 Speaking multiple device protocols is key in real networks.
 All device behaviors are described with device data models.

NSO Network Abstraction
OSS/BSS Network EMS/NMS
Engineer
NETCONF REST CLI WebUI SNMP
NSO JAVA/JavaScript Northbound APIs
Service Service Management Layer End-to-end Service

Models View
Device Device Management Layer Global Device View

Models
Network Element Driver (NED) NED NED NED Southbound APIs
Multivendor
Physical and/or
Virtual Device
Environment
Cisco NSO implements the Service Layer, the Network Operating System Layer and it also communicates
with the Forwarding Layer using either OpenFlow or through traditional means like CLI, SNMP or even
Remote Procedure Call (RPC). Cisco NSO uses components called Network Element Drivers to implement
this southbound communication. Northbound, that is towards operators or applications, the NSO is able to
speak a variety of different protocols. Regardless of the communication method, the Cisco NSO provides an
abstract network view to the operators and/or applications.
The power of Cisco NSO lies in its model-to-model mapping principles. It is able to describe complex
services at the Service Layer and map those services to device models, which represent different devices
from different vendors. This way, complex services can be described and implemented in a simple way and
pushed to the devices without having to worry about device vendor, configuration semantics, configuration
interfaces, etc.
NSO Architectural Components
Engineer
NSO JAVA/JavaScript Northbound APIs
Package Any scripting

Service Templates Manager
Script API
Service language
Models Manager
Core Alarm Developer Java or Python
Mapping Logic Manager API extensions
Engine
Device Device
CDB Notification
Models Manager FASTMAP Receiver ...
NETCONF REST CLI OpenFlow etc.
The logical architecture outlines the Cisco NSO two-layered approach: a device manager that simplifies
device interface integration and manages device configuration scenarios, and a service manager that applies
service changes to devices. At the core of Cisco NSO is the configuration datastore, Configuration Database
(CDB), which 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.
Cisco NSO addresses the mapping from a desired service configuration to the corresponding device
configuration through a dedicated mapping layer.
The network can be a mix of traditional equipment, virtual devices and OpenFlow switches. The latter
requires the Cisco NSO TailFlow module which is a distributed OpenFlow controller cluster.

NSO Use Case: Dynamic Service Chaining Example
Simple Service Management Interface for Dynamic End-to-End Service Management of Complex Services
NETCONF REST CLI SNMP

NSO
Service Service Templates
Models Manager
Mapping Logic
Device Device
Models Manager FASTMAP
CDB
NED NED NED
Traffic IPS/IDS Content WAN Firewall

Shaper Filtering acceleration
A A
B B
The figure illustrates one of the more complex service implementations where we can use Cisco NSO to
dynamically chain network service. The figure illustrates two service instances:
 Service A: end user resources are connected to the Internet using a traffic shaper, and IDS and a
firewall.
 Service B: end user resources are connected to the Internet using a content filtering appliance and a
WAN accelerator.
Cisco NSO enables the dynamic addition or removal of service in the service chain. Furthermore, such
services can be implemented using physical or virtual devices (or a combination).
Cisco NSO Architecture (Cont.)
Cisco NSO Core Engine

Transaction Management
 Performs core functionality
Session Management / Authentication  Glue for all NSO components
Role-based Access Control
 Reads initial configuration from
Redundancy / Replication ncs.conf
Event Logging / Audit Trailing
 All other configuration and
Validation (syntactic and semantic)
CDB
operational data is handled in
Rollback Management
the main configuration
Upgrades and Downgrades database (CDB)
The Cisco NSO Core engine handles fundamental functions like transactions, high availability replication,
upgrades/downgrades etc. All Cisco NSO operations are handled within the transaction manager. Cisco NSO
Core engine functionality can be summarized by the following:
 The transaction manager handles nested transactions between services and devices, and is capable to
roll-back service configurations across multiple devices.
 All NSO operations passes through a centralized AAA engine which handles authentication and session
management.
 Role based access control can be defined at any granularity level.
 When high availability is enabled in ncs.conf CDB automatically replicates data written on the master to
the connected slave nodes. Replication is done on a per-transaction basis to all the slaves in parallel. It
can be configured to be done asynchronously (best performance) or synchronously in step with the
transaction (most secure).
 All activities are logged in an audit log.
 NSO runs its own internal semantic and syntactic validation against the model constraints.
 NSO provides transaction rollback and saves configurations rollbacks in separate files.
 The Core engine also handles upgrades and downgrades.

Cisco NSO Components
This topic describes NSO components.
Device Manager
 Handles device  Service models map to  FASTMAP algorithm
configurations device configurations: controls and optimizes
 Configuration templates (XML) southbound configuration
 Device configuration actions:
framework defined using  Java or Python code
 Create
YANG data models from
NEDs  Modify
 Delete

NSO
Models Manager
Mapping Logic
Device Device
CDB
NED NED NED
The purpose of the Device Manager is to manage different devices using a clean YANG and Network
Configuration Protocol (NETCONF) view. Irrespective of underlying interface such as SNMP or CLI, the
device manager will provide a transactional view towards the devices. Users or programmers can then
configure the devices and read operational data from the devices in a unified way. When the device supports
YANG and NETCONF natively, the device manager is totally automatic. Non-NETCONF devices are
integrated using the Network Element Driver (NED) toolkit.
The Device Manager supports the following overall features:
 Quickly provision a new device by copy-and-edit either from other the configuration of another device
or from a template configuration.
 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 synch with the Cisco NSO database. If they
are not, what is the diff?
 Synchronize the Cisco NSO database and the configurations on devices, in case they are not in synch.
This can be done in either direction (import the diff to the Cisco NSO database or deploy the diff on
devices).
 Automatic and code-free integration to NETCONF (e.g., Juniper), Cisco-style CLI, and SNMP devices.
Limited amount of code to other proprietary interfaces.
Service Manager
 Service modeling using  Service activation  Service testing
YANG  Service modification  Aggregated operational data
 Mapping to device models  Service decommissioning
using templates (XML)
and/or Java or Python  Service restoration
code  Service synchronization
with device configurations

NSO
Models Manager
Mapping Logic
Device Device
CDB
NED NED NED
The Service Manager lets you develop service-aware applications, such as IPTV or Multiprotocol Label
Switching (MPLS) VPNs that configure devices. In this case the data models for the services are not defined
by the devices but they are the result of a modeling activity. Apart from the YANG modeling activity to
define the model, the model needs to be mapped into the corresponding device operations. In most cases this
is done by specifying configuration templates that transforms service parameters to device configuration
parameters. This can also be done programmatically "Mapping Logic" for more complex cases. Both of the
above approaches uses Cisco NSO FASTMAP (explained later), in order to simplify the mapping and also
handling the complete life-cycle such as modifying and deleting service instances.
The Service Manager addresses the following challenges:
 Modeling of services.
 Dynamic update of user and programmatic northbound interfaces from the service model without other
inputs.
 Short development and turn-around time for new services.
 Mapping the service model to device models.
 Validation of service configuration.
 Transaction-safe activation of services across different 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.

Templates
 Simplify changes in network configuration

 Two types:
 Device templates for direct activation (e.g. through NSO CLI, REST)
 Configuration templates for service mapping to device configurations

NSO
Models Manager
Mapping Logic
Device Device
CDB
NED NED NED
Templates is a flexible and powerful mechanism in Cisco NSO which simplifies how changes can be made
across the configuration data and also allows a declarative way to describe such manipulations. Templates
can be applied in a traditional "fire-and-forget" fashion by using them in actions, or through Cisco NSO
FASTMAP using templates as part of a service implementation. When a template is used as part of a service
implementation Cisco NSO remembers the configuration changes made towards the devices and the template
changes can for example be reverted.
Two different types of templates exist:
 device-templates: these templates are part of the NSO configuration. Device-templates are created and
changed in the tree /devices/template/config the same way as any other configuration data and are
affected by rollbacks and upgrades. Device-templates can only manipulate configuration data in the
/devices/device/config tree i.e. only device data.
 config-templates: these templates get loaded as part of packages. The config-templates are stored in
XML files in the templates sub directory of a package. Config-templates can be used to update any part
of the configuration.
Mapping Logic
Service
Parameters
 Transforms the service models to device models
 When templates are not enough:
 External call-outs can be made
Java or Python
 Expressions or algorithms in Java or Python code can be used code (optional)
 Uses FASTMAP
 1 page of code for a complex service
Configuration
NSO Template (XML)
Models Manager
Mapping Logic
Device Device
Device
CDB Configuration
NED NED NED
Mapping logic includes mechanisms for how service related operations are reflected on the devices. This
involves mapping a service operation to available operations on devices. For example, when you add an
access link to a VPN, how is this reflected on Customer Edge (CE) and Provider Edge (PE) routers?
The figure on the right illustrates the sequence of events when implementing the service-to-device mapping
logic:
 The service parameters are provided by the service manager
 Optionally, Java or Python code can be used to map the service parameters to the individual device’s
configuration template or have the parameters calculated by the code or retrieved using some other
means.
 The final set of parameters is used to fill in the variables in the device’s configuration template.
 The template is fed to the device manager to be optimized and sent down to the devices.

FASTMAP
 FASTMAP controls and optimizes southbound configuration actions:
 Create: defines the “to-be” state
 Modify: FASTMAP algorithm calculates the necessary changes to be applied
 Delete: FASTMAP algorithm stores the “undo” operation needed to revert to the original state
 Operator is only concerned with defining the “to-be” state (i.e. create operation)

NSO
Models Manager
Mapping Logic
Device Device
CDB
NED NED NED
How is the transformation from service models to device models defined? This is normally a complex
problem. It might look easy from a 1000 feet view, but when it comes to the actual configuration values for a
router there are configuration details that need to be well defined. Cisco NSO simplifies this drastically by
use of the FASTMAP algorithm. Typically, an engineer defines a higher level service model representing for
example the VPN service itself and this service shall result in actual device configurations.
FASTMAP enables automatic management of any kind of change and deletion of a service. All change
scenarios and deletion are inferred from a single definition of the creation of the service. The mapping from
the service create to the corresponding device configuration is defined in a high level API or through a
template. The programmer only has to define the service create method. If later on a user changes or deletes
an existing service Cisco NSO calculates the changes.
The result of this is close to magic - at any point in time a user or external client can modify a service and
Cisco NSO will automatically calculate the required minimum diff to the network. Also deleting a service
from the network will automatically clean up all configuration data on the devices. On top of this FASTMAP
automatically enables the following functions:
1. Service dry-run: if I apply this service to the network, what will happen? The output can be shown in a
data-model general way as well as a native CLI, NETCONF etc. output.
2. Service check-sync: is the service configuration in sync with the actual device configuration? This can
detect the case that a network engineer has modified the device configuration by using the native CLI
and that the change is in conflict with a desired service configuration. It can also show the minimum diff
to restore the service.
3. Service re-deploy: generate the minimum diff to restore a service and make it happen in the network.
Mapping Logic (Cont.)
Service Device Device
Model Model A Model B
2 x mapping logic
firewall filter ip
rule term access-list
source-ip-prefix: from source

10.1.1.0/24
prefix: 10.1.1.0/24 address: 10.1.1.0
source-port:
161 wildcard: 0.0.0.255
protocol: udp
protocol:
udp protocol: udp
port: 161 port: 161
to destination
According to the figure above the mapping needs to transform the service model instance to the device
models. This is done by using either a device template or the NAVU DOM tree data-structures in Java.
Manipulating data-structures is well-known for any programmer. No skills in network management technical
or protocol details are needed. What is needed is of course domain expertise in the service model and how it
is represented in the network.
The template snippet below uses Xpath to select all rule lists in the service model and creates the
corresponding Junos device-model data and sets the three configurables source-address, protocol and
destination-port.
firewall {
filter fw1 {
term "{rule/name}" {
from {
source-address "{source-ip-prefix}";
protocol [ "{protocol}" ];
destination-port [ "{source-port}" ];
}
then {
accept;
}
}
}
}

CDB
/ (root)
 Stores configuration data for devices
and system
 ACID compliant
 Fast, lightweight, fault-tolerant
 Compact binary XML-analogue devices services alarms snmp nacm
format
d1 s1
 In-memory DB with file system
journaling for persistence Service configuration
 1:N data replication support based on service’s
 In-service data model update config YANG model
 Automatic schema and data update
Device configuration
 Automatic loading of initialization based on device’s
data
YANG model
Cisco NSO uses Configuration Database (CDB) to store its own configuration, the configuration of all
services, as well as a copy of the configuration of all managed devices. CDB is a RAM database, the entire
configuration is kept in RAM at all times. Thus if we use Cisco NSO to manage a large network, we need a
lot of RAM memory. CDB is also persistent, all transactions are written to disk in journal files.
By default, Cisco NSO stores all configuration data in CDB. The alternative is to use an external database as
shown in the examples. Cisco NSO/getting-started/developing-with-Cisco NSO/6- extern-db. There are a
number of advantages to CDB compared to using some external storage for configuration data. CDB has:
 A solid model on how to handle configuration data in network devices, including a good update
subscription mechanism.
 A networked API whereby it is possible for an unconfigured device to find the configuration data on the
network and use that configuration.
 Fast lightweight database access. CDB by default keeps the entire configuration in RAM as well as on
disk.
 Ease of use. CDB is already integrated into Cisco NSO, the database is lightweight and has no
maintenance needs. Writing instrumentation functions to access data is easy.
 Automatic support for upgrade and downgrade of configuration data. This is a key feature, which is
useful not only when performing actual up/downgrades of Cisco NSO itself. It also greatly simplifies
the development process by allowing individual developers to add/delete items in the configuration
without any impact whatsoever on other developers. This will be fully described later.
Alarm Manager device
device
device
object
 Manages native alarms and provides: object
object
 Extensible alarm-types alarm-type
Alarm
alarm-type model
 Configurable mapping to alarm alarm-type
standards
specific-
 Northbound SNMP Alarm MIB specific-
specific-
problem
problem
problem
 CDB knows device – service mapping
cleared
cleared
active
time time
time time
time time
sev user
sev user
Services sev user
State and model-based text state
correlation rather than text state
Devices text state
notification-based
Resource Operator
Cisco NSO embeds a generic alarm manager. It is used for managing Cisco NSO native alarms and can
easily be extended with application specific alarms. Alarm sources can be notifications from devices,
undesired states on services detected or anything provided via the Java API.
The alarm manager is accessible over all northbound interfaces. A read-only view including an SNMP alarm
table and alarm notifications is available in an SNMP Alarm MIB. This MIB is suitable for integration to
SNMP based alarm systems.
First of all it is important to clearly define what an alarm means. “An alarm denotes an undesirable state in a
resource for which an operator action is required.” Alarms are often confused with general logging and event
mechanisms, thereby flooding the operator with alarms. In Cisco NSO, the alarm manager shows undesired
resource states that an operator should investigate. Cisco NSO contains other mechanisms for logging in
general. Therefore, Cisco NSO does not naively populate the alarm list with traps received in the SNMP
notification receiver.
Before looking into how Cisco NSO handles alarms it is important to define the fundamental concepts. We
make a clear distinction between alarms and events in general. Alarms should be taken seriously and be
investigated. Alarms have states, they go active with a specific severity, they change severity and they are
cleared by the resource. The same alarm may become active again. A common mistake is to confuse the
operator view with the resource view. The model described so far is the resource view. The resource itself
may consider the alarm cleared. The alarm manager does not automatically delete cleared alarms. An alarm
that has existed in the network may still need investigation. There are dedicated actions an operator can use
to manage the alarm list, for example delete alarms based on criteria's such as cleared and date. These actions
can be performed over all north-bound interfaces.

Northbound APIs
This topic describes the available APIs that can be used to access Cisco NSO.
Northbound APIs
 Human interaction:
 NSO CLI Network
OSS/BSS EMS/NMS
Engineer
 WebUI
 Automation integration:
 NETCONF, REST, JSON/RPC NSO
Models Manager
Mapping Logic
 Monitoring: Device Device
 SNMP, NETCONF Models Manager FASTMAP
CDB
NED NED NED
The figure illustrates the available northbound APIs:

 The NSO CLI and the WebUI are primarily intended for direct human interaction.
 NETCONF, REST and JSON/RPC are primarily intended for implementing automation (i.e. integration
with other OSS/BSS/BPM systems).
 SNMP is primarily intended for the monitoring of NSO. NETCONF can also be used to forward
notifications to external systems.
Cisco NSO Server User Interfaces
root@NCS:/opt/ncs/ncs-4.1.1/# ls -l
total 368
Shell drwxr-xr-x 2 root root 4096 Jun 28 12:46 bin
SSH on port 22 -rw-r--r-- 1 root root 140956 Jun 28 12:47 CHANGES
drwxr-xr-x 4 root root 4096 Jun 27 21:36 doc
CLI admin@ncs# show ncs-state version3 root root
drwxr-xr-x 4096 Jun 28 12:46 erlang
SSH on port 2024 version 4.1.1; drwxr-xr-x 3 root root 4096 Jun 28 12:45 etc
admin@ncs# drwxr-xr-x 10 root root 4096 Jun 28 12:50 examples.ncs
WebUI drwxr-xr-x 2 root root 4096 Jun 28 12:46 include
Cisco NSO HTTP on port 8080 drwxr-xr-x 3 root root 4096 Jun 28 12:45 java
Server drwxr-xr-x 5 root root 4096 Jun 28 12:48 lib
-rw-r--r-- 1 root root 128459 Jun 28 12:47 LICENSE
drwxr-xr-x 5 root root 4096 Jun 27 21:34 man
-rw-r--r-- 1 root root 541 Jul 4 14:10 ncsrc
-rw-r--r-- 1 root root 509 Jul 4 14:10 ncsrc.tcsh
drwxr-xr-x 3 root root 4096 Jul 4 14:10 netsim
drwxr-xr-x 17 root root 4096 Oct 28 10:40 packages
-rwxr--r-- 1 root root 17694 Jun 28 12:47 README
drwxr-xr-x 4 root root 4096 Jun 28 12:46 scripts
drwxr-xr-x 3 root root 4096 Jun 28 12:45 src
drwxr-xr-x 4 root root 4096 Jun 28 12:47 support
drwxr-xr-x 3 root root 4096 Jun 28 12:45 var
-rw-r--r-- 1 root root 220 Jun 28 12:47 VERSION
 The ncs.conf file contains the server configuration with default management ports
Cisco NSO server provides three main user interfaces:

 Shell access to the server using Secure Shell (SSH). This method is used to manage the hosting server
and optionally to manage service models that reside on the file system.
 Cisco NSO CLI to manage server, devices and services.
 Cisco NSO GUI to manage server, devices and services.
The server configuration can be modified by editing the ncs.conf file located in the ./etc/ncs subdirectory
of the NSO root directory. Use man ncs.conf to access detailed information about the contents and
options of the configuration file.
The figure above highlights two directories in bold blue:
 example.ncs: this directory contains self-sufficient Cisco NSO instances with sample services.
 packages: this contains the device and service packages.

Cisco NSO CLI Overview
 Single point of configuration
 Supports Cisco and Juniper style CLI:
 Easier adoption by operators based on existing experience
 Either style can be used regardless of the actual configured device type
 Two CLI modes similarly to most network devices:
 Operational mode: mostly for operation and monitoring purposes
 Configuration mode: for system and device configuration
At this time we should get familiar with the basics of the Cisco NSO CLI. The Cisco NSO CLI comes in two
flavors to accommodate the existing CLI familiarity of the majority of network operators:
 Juniper style CLI
 Cisco style CLI
Like most network devices, the Cisco NSO CLI also has two modes of operation:
 The operational mode allows us to manage the device and the server. This mode is primarily used by the
operations to monitor and maintain the environment.
 The configuration mode allows us to configure the services, devices and the server. This mode is
typically used by service fulfillment within operations, engineering as part of support, etc.
Cisco NSO CLI Overview (Cont.)
admin@ncs# ?
Possible completions:
alarms - Alarm management
autowizard - Automatically query for mandatory elements
cd - Change working directory
clear - Clear parameter
cluster - Cluster configuration
compare - Compare running configuration to another configuration or a file
complete-on-space - Enable/disable completion on space
compliance - Compliance reporting
config - Manipulate software configuration information
describe - Display transparent command information
devices - The managed devices and device communication settings
display-level - Configure show command display level
...
Usability characteristics:
 Auto-completion using tab or space characters
 Question mark for syntax help and command description
Similar to most network devices' CLIs, you can use auto-completion (space or tab) on commands and use the
question mark to get syntax help.

Cisco NSO CLI for Configuration
Cisco Style Juniper Style
admin@ncs# admin@ncs> configure
admin@ncs# config Entering configuration mode private
admin@ncs(config)# [ok][2016-01-27 11:14:12]
admin@ncs(config)# devices device PE11
... [edit]
admin@ncs(config-device-PE11)# top admin@ncs% set devices device PE11 ...
admin@ncs(config)# exit | commit | abort admin@ncs% exit | commit | revert
admin@ncs# [ok][2016-01-27 11:15:44]
admin@ncs# show running-config admin@ncs> show configuration
cluster authgroup default cluster {
default-map same-user authgroup default {
default-map same-pass default-map {
umap admin same-user;
same-user same-pass;
... }
...
switch cli
 Two modes: operational and configuration (use the config and exit commands to switch between them)
 Two CLI styles: Cisco and Juniper (use the switch cli command to switch between them)
The config command can be used to go from the operational mode into the configuration mode. The exit
command can be used to go back from the configuration mode into the operational mode.
Among other things, the two CLI flavors differ in how they show which mode you are in. The Cisco style
uses the hash sign ("#") to represent the privileged operational mode and the config keyword ("(config)#")
to represent the configuration mode. The Juniper style uses the greater sign (">") to represent the operational
mode and the percent sign ("%") to represent the configuration mode.
The switch cli command can be used to switch between the two CLI styles.
The commit command will commit and deploy the changes in configuration.
The abort (or revert) command will throw away the changes and exit the configuration mode.
The exit command will exit the configuration mode and prompt for commit if there are any changes pending.
Packages
This topic describes the concept of packages used in Cisco NSO to manage any custom
additions to the system.
Package Manager
 Loads and manages packages  Primary package types:
 All additions to core NSO functionality  Device NED’s
are deployed as packages:  Services
 Simplifies deployment
 Enables Hot-deploy/redeploy/upgrade
NSO JAVA/JavaScript
Package
Script API
Service
Models Manager
Core Alarm Developer
Mapping Logic Manager API
Engine
Device Device
CDB Notification
Network Element Driver (NED) NED NED NED
All user code that needs to run in Cisco NSO must be part of a package. A package is basically a directory of
files with a fixed file structure. A package consists of code, YANG modules, and custom WebUI widgets etc.
that are needed in order to add an application or function to Cisco NSO. Packages are a controlled way to
manage loading and versions of custom applications.

Package Structure packages Central repository of all packages
mypkg Package directory

 Each package is contained within a Defines package
dedicated directory package-meta-data.xml
components to load
 YANG model defines package’s src Package sources
configuration schema
./mypkg/src/yang/mypkg.yang Makefile Defines components to compile
 Templates are used to map service
data to device configuration data yang YANG model
./mypkg/templates/mypkg.xml
java Java code (optional)
 Java or Python code can be used to
augment the default functionality templates XML templates (for mapping)
./mypkg/src/java/src/com/acme/mypkg/mypkg.java
© 2016 Cisco and/or its affiliates. All rights reserved.

python Python code (optional)
Cisco Network Services Orchestrator 27
Each package consists of a number of components which are located in a dedicated package directory:
 The package-meta-data.xml file defines the package components to load by NSO.
 The src directory contains the source code for the package including the YANG model and the optional
Java code.
 The templates directory contains the XML configuration templates that are used to map service
parameters to device configurations.
Package Management
1. Create packages: ncs-make-packages

 Simplifies initial package creation by creating a skeleton directory and file structure
2. Develop package:
 Use a text editor or an appropriate IDE to develop the package by modifying and creating
the necessary files (YANG, Java, Python, XML templates)
3. Compile packages: make

 Includes syntax and semantic verification of package definitions
 Reads the Makefile to determine the components to compile
4. Reload packages: packages reload (in NSO CLI)

 Activates new packages or upgrades existing packages
 Reads the package-meta-data.xml file to determine which components to load
The figure illustrates the three main steps in the creation process for a new package:
1. Create a package skeleton using the ncs-make-packages tool.
2. Develop the package by using a text editor or an appropriate IDE to develop the package by modifying and
creating the necessary files (YANG, Java, Python, XML templates)
3. When done, compile the package by issuing the make command in the src subdirectory.
4. Activate the package by issuing the packages reload command in NSO CLI.

Network Element Drivers
This topic describes the Network element Drivers (NEDs) as a subset of possible NSO
packages used to provide management access to managed devices.
Network Element Driver

 Used to communicate southbound NSO NETCONF REST CLI SNMP
 They are completely model driven: Service Service Templates

Models Manager
 YANG device models Mapping Logic
Device Device
 Deployed as NSO packages Models Manager FASTMAP
CDB
 NED types: NETCONF CLI SNMP Generic
 NETCONF NED: YANG model
 CLI NED: YANG model
+ YANG extensions to map CLI and YANG
+ Java code for SSH communication
 SNMP NED: YANG model
 Generic NED: YANG model
+ framework for an arbitrary NED implementation
Network Services Orchestrator (NSO) knows how to automatically communicate southbound to Network
Configuration Protocol (NETCONF) and Simple Network Management Protocol (SNMP) enabled devices.
By supplying NSO with the YANG models of a NETCONF device, NSO knows the data models of the
device, and through the NETCONF protocol knows exactly how to manipulate the device configuration. This
can be used for a NETCONF enabled device, any device that uses ConfD as management system, or any
other device that runs a compliant NETCONF server. Similarly, by providing NSO with the MIBs for a
device, NSO can automatically manage such a device.
Reality today is that many of the existing devices in current networks do not speak NETCONF and SNMP is
usually mostly used to retrieve data from devices. By far the most common way to configure network
devices is through the CLI. Management systems typically connect over Secure Shell (SSH) to the CLI of the
device and issue series of CLI configuration commands. Some devices do not even have a CLI, and thus
SNMP, or even worse, various proprietary protocols, are used to configure the device. NSO can speak
southbound not only to NETCONF-enabled devices, but through the NED architecture it can speak to an
arbitrary management interface. This is of course not entirely automatic like with NETCONF, and depending
on the type of interface the device has for configuration, this may involve some programming. SNMP
devices can be managed automatically, by supplying NSO with the MIBs for the device, with some
additional declarative annotations. Devices with a Cisco style CLI can be managed by writing YANG models
describing the data in the CLI, and a relatively thin layer of Java code to handle the communication to the
devices. Other types of devices require more coding.
NED in NSO Architecture
NSO
Models Manager
Mapping Logic
Device Device
CDB
NETCONF CLI SNMP Generic

NED NED NED NED
CLI REST
NETCONF SOAP
over SNMP
over SSH WS
SSH
etc.
The NSO architecture is described in the picture, with a built-in NED for NETCONF, a NED for SNMP, one
NED for Cisco CLIs, and a generic NED for other protocols. The NED is the adaptation layer between the
XML representation of the network configuration contained inside NSO and the wire protocol between NSO
and managed devices. The NETCONF and SNMP NEDs are built in, the CLI NED is entirely model driven,
whereas the generic NED requires a Java program to translate operations on the NSO XML tree into
configuration operations towards the device. Depending on what means are used to configure the device, this
may be more or less complicated.

NED Code States
 NED code goes through
different states in the life of a Send Data
transaction Prepare to device
 Not all NED implementations

may make advantage of all
Send
states; typically due to device
Commit Abort Confirmed
limitations Commit
 Ideally, devices should 
support NETCONF with
Send
confirmed-commit capability
Persist Revert Confirming
to take advantage of all Commit
transaction states  
NSO differentiates between managed devices that can handle transactions and devices that cannot.
PREPARE
In the prepare phase, the NEDs get exposed to all the changes that are destined for each managed device
handled by each NED. It is the responsibility of the NED to determine the outcome here. If the NED replies
successfully from the prepare phase, NSO assumes the device will be able to go through with the proposed
configuration change.
ABORT
If any participants in the transaction reject the proposed changes, all NEDs will be invoked in the abort()
method for each managed device the NED handles. It is the responsibility of the NED to make sure that
whatever was done in the PREPARE phase is undone.
COMMIT
Once all NEDs that get invoked in commit(Timeout) reply ok, the transaction is permanently committed to
the system. The NED may still reject the change in COMMIT. If any NED reject the COMMIT, all
participants will be invoked in REVERT, NEDs that support confirmed commit with a timeout (e.g. Cisco
IOS XR), may choose to use the provided timeout to make REVERT easy to implement.
REVERT
This state is reached if any NED reports failure in the COMMIT phase. Similar to the ABORT state, the
reverse diff is supplied to the NED if the NED has asked for that.
PERSIST
This state is reached at the end of a successful transaction. Here it's the responsibility of the NED to make
sure that if the device reboots, the changes are still there.
NETCONF NED NSO NETCONF REST CLI SNMP

Models Manager
YANG Mapping Logic
 Native NED for NSO Device Device Device
Models Manager FASTMAP CDB
 No coding required Model
NETCONF CLI SNMP Generic
 Only YANG device model NED NED NED NED
required
 Can be used with any device NETCONF XML
supporting NETCONF (e.g. by over SSH Config
incorporating ConfD)
Having a NETCONF server on a device enables the NSO to communicate directly with the device. No
coding is required to support device configuration. Some, but not all vendor support this capability.
NSO knows how to automatically communicate southbound to NETCONF and SNMP enabled devices. By
supplying NSO with the YANG models of a NETCONF device, NSO knows the data models of the device,
and through the NETCONF protocol knows exactly how to manipulate the device configuration. This can be
used for a NETCONF capable device, any device that uses ConfD as management system, or any other
device that runs a compliant NETCONF server. Similarly, by providing NSO with the MIBs for a device,
NSO can automatically manage such a device using SNMP.

CLI NED NSO NETCONF REST CLI SNMP

Models Manager
Mapping Logic
 YANG device model: Device Device
 Device config options CDB
CLI
 CLI syntax through YANG NETCONF
NED
SNMP Generic
NED NED NED
extensions XML
Config
 Internally uses NETCONF (i.e. YANG
ConfD
XML) Device
Model Java for
SSH
 ConfD converts to and from
between XML and CLI
CLI
CLI Config
over SSH
The CLI NED is an entirely model driven way to CLI script towards all Cisco like devices. The basic idea is
that the Cisco CLI engine found in ConfD, can be run in both directions:
 A sequence of Cisco CLI commands can be turned into the equivalent manipulation of the internal XML
tree that represents the configuration inside NCS/ConfD. This is the normal mode of operations of
ConfD, run in Cisco mode. A YANG model, annotated appropriately, will produce a Cisco CLI. The
user can enter Cisco commands and ConfD will, using the annotated YANG model, parse the Cisco CLI
commands and change the internal XML tree accordingly. Thus this is the CLI parser and interpreter.
Model driven.
 The reverse operation is also possible. Given two different XML trees, each representing a configuration
state, in the ConfD case it represents the configuration of a single device, i.e. the device using ConfD as
management framework, whereas in the NSO case, it represents the entire network configuration, we
can generate the list of Cisco commands that would take us from one XML tree to another. This
technology is used by NSO to generate CLI commands southbound when we manage Cisco like
devices.
Generic NED NSO NETCONF REST CLI SNMP

Models Manager
Mapping Logic
 Custom implementation of Device Device
Manager FASTMAP
southbound protocol Models CDB
Generic
NETCONF CLI SNMP
 Custom ConfD implementation NED NED NED
NED
to convert between XML and XML
Config
southbound protocol YANG ConfD
Device
Model Java for
Protocol X
Protocol X
Config
A generic NED is required when we want to manage a device that neither speaks NETCONF or SNMP, nor
can be modeled so that ConfD - loaded with those models - gets a CLI that looks almost/exactly like the CLI
of the managed device. For example devices that have other proprietary CLIs, devices that can only be
configured over other protocols such as Representation State Transfer (REST), Common Object Request
Broker Architecture (Corba), Extensible Markup Language-Remote Procedure Call (XML-RPC), Simple
Object Access Protocol (SOAP), other proprietary XML solutions, etc. In a manner similar to the CLI NED,
the Generic NED needs to be able to connect to the device, return the capabilities, perform changes to the
device and finally, grab the entire configuration of the device.
The interface that a Generic NED has to implement is very similar to the interface of a CLI NED.
When NSO has calculated a diff for a specific managed device, it will also calculate for CLI NEDs the exact
set of CLI commands to send to the device, according to the YANG models loaded for the device. In the case
of a generic NED, NSO will instead send an array of operations to perform towards the device in the form of
Digital Optical Monitoring (DOM) manipulations. The generic NED class will receive an array of
NedEditOp objects.
Each NedEditOp object contains:

 The operation to perform, i.e. CREATED, DELETED, VALUE_SET etc.
 The keypath to the object in case.
 An optional value.
 When NSO wants to sync the configuration from the device to NSO, the CLI NED only has to issue a
series of show running-config [toptag] commands and reply with the output received from the device.
A generic NED has to do more work. It is given a transaction handler, which it must attach to over the
Maapi interface. Then the NED code must - by some means - retrieve the entire configuration and write
into the supplied transaction, again using the Maapi interface.
Once the generic NED is implemented all other functions in NSO work precisely in same manner as with
NETCONF and CLI NED devices. NSO still has the capability to run network wide transactions. The caveat
is that to abort a transaction towards a device that doesn't support transactions, we calculate the reverse diff

and send it to the device, i.e. we automatically calculate the undo operations. Another complication with
generic NEDs is how the NED class shall authenticate towards the managed device. This depends entirely on
the protocol between the NED class and the managed device. If SSH is used to a proprietary CLI, the
existing authgroup structure in NSO can be used as is. However, if some other authentication data is needed,
it is up the generic NED implementer to augment the authgroups in tailf-ncs.yang accordingly.
NSO
Netsim Service Service Templates
Models Manager
Mapping Logic
 Optional add-on to NEDs Device Device
Models Manager FASTMAP CDB
 Simulates device’s native CLI NETCONF
CLI
SNMP Generic
NED
NED NED NED
 Useful for development and XML
Config
testing
YANG
ConfD
Device NSO normally
 Lightweight: enables simulation Model Java for managing a device as
of many devices on a desktop SSH if it were real
CLI
 Uses YANG model and ConfD CLI over SSH Config
in reverse to simulate a device’s
Java for
CLI SSH srv. Netsim
Netsim simulating
ConfD
device’s CLI
The ncs-netsim program is a useful tool to simulate a network of devices to be managed by NSO. It makes it
easy to test NSO packages towards simulated devices. All you need is the NSO NED packages for the
devices that you need to simulate. The devices are simulated with the Tail-f ConfD product.

Available NEDs
Vendor Device/Platform Vendor Device/Platform Vendor Device/Platform
A10 ACOS (AX Series) Cisco ASA-OS (ASAv)
Overture 1400, ISG2200,
Networks StarOS (ASR 5000 Series)
ISG5000, ISG5100,
Accedian MetroNID (AMN-1000-TE) PNR (PNR >= 8.1)
ISG5500, ISG6000
UCS (UCS 2.2.1)
Adva FSP150CC-825, Palo Alto PAN-OS
FSP150CCf-815 Clavister cOS Core
Networks
Alcatel- SR OS (7750, 7450) Dell Force10 FTOS (S4810)
Pulsecom SuperG
Lucent Ericsson EFN324C, Redback SE
Quagga BGP
Allied CentreCOM x210 F5 Networks BIG-IP FW, LB, LTM 1600,
Telesis LTM VM Riverbed Steelhead CXA 1555-
Arista DCS 7100-series Fortinet FortiOS (Fortigate 3240C, B010, VCX-1555-M
Avaya VSP 9000-, SR 8000- and 200B-BDL, VM02) Sonus SBC 5x00
ERS H3C Comware (S5800) etc.
Brocade MLXe-4, Vyatta Plus Huawei Quidway S3300
Note! Not all features may
CableLabs CCAP Infinera DTNX
be available and may require
Ciena ESM, ASOS (5150, 5140) Juniper Junos (MX, SRX, etc.)
Cisco IOS, IOS XE, IOS XR, NX- NEC iPASOLINK 400
development
OS Nominum DCS
The figure illustrates some of the currently supported vendors and devices. Note that this is a constantly
growing list bot in the number of vendors, devices and the functionality that is supported by NEDs.
Note that is a device is on the list of supported devices it does not necessarily mean that the NED supports all
the required functionality. It may be required to request from Cisco to add additional support based on the
presented requirements.
NED Development Process
NED Delivery NED Delivery
NED Delivery
Sales Development/ Testing Acceptance /
Analysis / Preparation Iterations (1+n) Support
Input:
Use Case(s) Device(s): Scoping: YANG-model  Update
 Configuration(s)  Requirements Java-code documentation
 Userguide(s) Lux-script(s)  Delivery server
 Access
(remote/VM/physical)*
 If support case:
 additional logs Planning:
 Resources Testing
 Estimates QA Acceptance
The official NED development process has its own development cycle. If a certain device is currently not
supported, a use case for the device is gathered. This stage requires device configuration access. The new
NED will cover device functionality required to deliver a certain business case and will normally not cover
all available functions of a device. The result of the development process is a device YANG model, some
Java code and scripts. These need to be thoroughly tested and the NEDs need to go through a Quality
Assurance phase before they are put into production environment.
Note If there is a need to develop a new NED, the best way to go about is to contact Cisco NSO team. Most
likely the work required will need supervision and support from experienced NED developers.

Summary
 YANG modelling is at the core of Cisco NSO and Cisco NSO is a true model driven
application.
 Cisco NSO has two main layers: the Device Manager and Service Manager. The Service
Manager lets you develop service-aware applications and the purpose of the Device
Manager is to manage different devices using YANG and NETCONF.
 FASTMAP algorithm is used for automation and management of any kind of change or
deletion of a service instance.
 Cisco NSO has a built in alarm manager. It is used for managing Cisco NSO native alarms
and can be extended with custom alarms.
References
 Cisco NSO documentation and manual pages.
Lesson 1-3
NETCONF Overview
Overview
This lesson provides an overview of the standard Network Configuration Protocol (NETCONF)
that can be used to manage network devices.
Objectives
 Understand the challenges of network management in complex and mixed environments
 Understand the benefits of NETCONF in mitigating the management challenges
 Understand the main NETCONF concepts
Challenges of Network Management
This topic describes some of the main challenges of network management.
Network Management Characteristics
Device 1: Device 2: Device 3: Device 4: Device 1233:

Vendor A Vendor A Vendor A Vendor B Vendor W
Model X Model X Model Y Model Z Model T
Version 1.2 Version 1.4 Version 1.3 Version 9.5 Version F
 Different management interfaces

 Different capabilities
The figure illustrates a typical service provider network environment where there may be a number of
network devices from different vendors and of different types and software versions. This significantly adds
to the complexity of managing services supported by the devices.
?
 Learn all management interfaces

 Understand the capabilities and limitations of each device and device group
 Ensure consistency and reliability of configurations across all devices
 Backup and restore configurations
A network management solution and the operator must be aware of the complexity of the network:
 Learn all management interfaces.
 Understand the capabilities and limitations of each device group.
 Ensure consistency and reliability of configurations.
 Backup configurations (and restore if/when needed).
 Provides a network topology view at best, lacking services view.

Network Management Solution
SNMP!

 Good intentions, but poor result in practice

 Today, SNMP is primarily only used for monitoring
 Possible reasons:
 Most IETF standards are influenced by network equipment vendors
 Operators’ input was missing in determining what features are required for efficient network management
Simple Network Management Protocol (SNMP) is an old protocol that was designed for network
management. In reality, SNMP is typically only used for network monitoring.
The SNMP is not so “Simple” and has severe limitations. Today it’s being mainly used to poll the network
on statuses not so much for configuring devices let stand end-to-end services.
Network Management Solution – Take 2

Operators Analysis of existing

management RFC 3535
Vendors protocols
In fact, there were many other “takes” on this challenge such as Common Management Information Protocol
(CMIP), SNMP, Common Object Request Broker Architecture (CORBA), Common Information Model
(CIM), Simple Object Access Protocol (SOAP), Representation State Transfer (REST), etc. All of these
never resulted in a widespread use for network management across different vendors and platforms.
The IETF used a different approach by inviting service providers to the table and enquiring what they (as
operators) would expect from a good network management system. This resulted in the creation of RFC 3535
which summarizes a number of requirements for network management.

RFC 3535: 14 Specific Requirements
1. Ease of use!
2. Clearly separating configuration and operational data
3. Ability to compare configurations and operational data across devices
4. Service and network management, not device management
5. Network wide transactions
6. No unnecessary configuration changes
7. Backup and Restore configurations
8. Support for multiple configuration sets
9. Standardized data models
10. Validation of configuration which should be text based
11. Role-Based Access Control (RBAC) to support the least-privilege model
12. Ability to perform consistency checks of access control across devices
13. Delayed, orchestrated activation of configuration
14. Data and task oriented RBAC support
The following is a summary of RFC 3535 findings:

1. Ease of use is a key requirement for any network management technology from the operators' point of
view.
2. It is necessary to make a clear distinction between configuration data, data that describes operational
state and statistics.
3. It is required to be able to fetch separately configuration data, operational state data, and statistics from
devices, and to be able to compare these between devices.
4. It is necessary to enable operators to concentrate on the configuration of the network as a whole rather
than individual devices.
5. Support for configuration transactions across a number of devices would significantly simplify network
configuration management.
6. Given configuration A and configuration B, it should be possible to generate the operations necessary to
get from A to B with minimal state changes and effects on network and systems. It is important to
minimize the impact caused by configuration changes.
7. A mechanism to dump and restore configurations is a primitive operation needed by operators.
Standards for pulling and pushing configurations from/to devices are desirable.
8. It must be easy to do consistency checks of configurations over time and between the ends of a link in
order to determine the changes between two configurations and whether those configurations are
consistent.
9. Network wide configurations are typically stored in central master databases and transformed into
formats that can be pushed to devices, either by generating sequences of CLI commands or complete
configuration files that are pushed to devices. There is no common database schema, although the
models used by various operators are probably very similar. It is desirable to extract, document, and
standardize the common parts of these network wide configuration database schemas.
10. It is highly desirable that text processing tools such as diff, and version management tools such as
revision control system (RCS) or concurrent versions system (CVS), can be used to process
configurations, which implies that devices should not arbitrarily reorder data such as access control lists.
11. Typical requirements are a role-based access control model and the principle of least privilege, where a
user can be given only the minimum access necessary to perform a required task.
12. It must be possible to do consistency checks of access control lists across devices.
13. It is important to distinguish between the distribution of configurations and the activation of a certain
configuration. Devices should be able to hold multiple configurations.
14. SNMP access control is data-oriented, while CLI access control is usually command (task) oriented. As
such, it is a requirement to support both data-oriented and task-oriented access control.

Implications of RFC 3535
Legacy Situation vs. The Future
OSS
NMS
EMS
Operations Equipment
 Lack of atomicity
 Ordering problem
Legacy  Complexity of management
Cost and protocol / CLI
Element complexity Information leakage Cost
 Difficulty automating tasks
Management  Lack of programmability
capabilities
 Etc.
Network-Wide Reduced Require Cost/

cost and  Greatly improved manageability
Transactions transactions Value and reliability
complexity
The typical current network management environment has the following characteristics:
 Per-vendor and/or per service management systems.
 Lack of integration between the systems.
 Complex and costly to understand and manage the environment (operations is more costly than the
systems that are being managed).
One of the requirements set forth in RFC 3535 is to make management transaction oriented and network
wide:
 Make devices transparent to the operator.
 Use transactions for provisioning.
 Provide automation and reliability (verification, rollback capabilities).
Network Management Solution – Take 2
Service Models
YANG
NETCONF

NETCONF!
Analysis of
Operators Ongoing RFC 4741  6241
existing
RFC 3535 standards
management RFC 5539
Vendors protocols
development
…
The findings of RFC 3535 resulted in the creation of a new standard protocol for network management –
NETCONF. The figure illustrates the approach where the standard protocol provides configuration
management across a variety of devices (different vendors, platforms, software versions).
The NETCONF protocol provides mechanisms to install, manipulate, and delete the configuration of network
devices. It uses an Extensible Markup Language (XML)-based data encoding for the configuration data as
well as the protocol messages. The NETCONF protocol operations are realized as remote procedure calls
(RPCs).
The NETCONF protocol defines a simple mechanism through which a network device can be managed,
configuration data information can be retrieved, and new configuration data can be uploaded and
manipulated. The protocol allows the device to expose a full, formal application programming interface
(API). Applications can use this straightforward API to send and receive full and partial configuration data
sets.
The NETCONF protocol uses a remote procedure call (RPC) paradigm. A client encodes an RPC in XML
and sends it to a server using a secure, connection-oriented session. The server responds with a reply
encoded in XML. The contents of both the request and the response are fully described in XML document
type definitions (DTDs) or XML schemas, or both, allowing both parties to recognize the syntax constraints
imposed on the exchange.
A key aspect of NETCONF is that it allows the functionality of the management protocol to closely mirror
the native functionality of the device. This reduces implementation costs and allows timely access to new
features. In addition, applications can access both the syntactic and semantic content of the device's native
user interface.

Why Use NETCONF?
 NETCONF was designed to conform to RFC 3535

 NETCONF greatly improves on the characteristics of SNMP and other protocols
 Today, NETCONF may be a competitive advantage, tomorrow it will be a must-
have
 Many service providers already require NETCONF and YANG in devices
 Combined NETCONF and YANG result in faster service deployment at reduced
overall costs for service providers
In order to achieve the goals set forth in RFC 3535, we should use the new approach by managing network
devices using NETCONF and designing services using YANG data modeling language.
A growing number of major vendors (e.g. Cisco, Juniper, Brocade, Ericsson, Huawei …) already support
NETCONF to some degree and the support is growing continuously as the service providers increasingly
make NETCONF a requirement in their projects.
Introduction to NETCONF
This topic describes the benefits of NETCONF in mitigating the management challenges.
NETCONF High-Level Properties
Network management protocol specifically designed to support service activation

and provisioning
 Encrypted, efficient transport: XML content transported over SSH+TCP
 Extensible: XML Namespaces make it possible to add e.g. new RPC types or
new table columns without breaking existing applications
 Transactional: configuration changes happen all-or-nothing and all-at-once
which simplifies network management applications
 Network-wide: can address multiple network elements in parallel to implement
network-wide transactions
NETCONF uses a simple RPC-based mechanism to facilitate communication between a client and a server.
The client can be a script or application typically running as part of a network manager. The server is
typically a network device.
A NETCONF session is the logical connection between a network administrator or network configuration
application and a network device. Global configuration attributes can be changed during any authorized
session, and the effects are visible in all sessions. Session-specific attributes affect only the session in which
they are changed.
The main advantages of NETCONF are:
 Sessions use encrypted and efficient transport: XML content transported over Secure Shell (SSH) over
TCP.
 Messages use XML which allows the framework to be augmented (e.g. new RPC types or new table
columns without breaking existing applications).
 NETCONF is transactional which means that configuration changes happen using the all-or-nothing and
all-at-once approach which simplifies network management applications.
 NETCONF is network-wide which means that a transaction can address multiple network elements in
parallel.

What Makes NETCONF/YANG Different? (Cont.)
SNMP NETCONF SOAP REST
Standard IETF IETF W3C -
Resources OIDs Paths URLs
Defined in YANG
Data models
MIBs Models
Undefined, (WSDL),
Data Modeling Language SMI YANG (WSDL, not data)
WADL, text…
In the XML Schema, Generic HTTP operations,
Management Operations SNMP NETCONF
not standardized POST, GET, PUT, PATCH
Encoding BER XML XML XML, JSON,…
SSH SSL SSL
Transport Stack UDP SSL HTTP HTTP
TCP TCP TCP
The additional characteristic of the NETCONF / YANG approach is that the entire stack representing the
management solution is standardized:
 XML for data encoding
 YANG for data modeling
 XPaths for data referencing
Comparison: SNMP vs. NETCONF
SNMP NETCONF NETCONF advantages:

GET <get-config>
 More configuration-oriented
GET-NEXT <edit-config>
 Better at bulk operations
SET <copy-config>
GETBULK <delete-config>  Capabilities negotiation:
TRAP <get>  Enables extensions (standard or proprietary)
INFORM <lock>  Less need to release new versions (current 1.1)
<unlock>  End-device functionality encoded in YANG
models anyway
<close-session>
<kill-session>
The next comparison shows how NETCONF builds on top of SNMP:

 Better support for configuration management.
 Better transport and support for bulk operations resulting in better performance and reliability.

Comparison: SNMP vs. NETCONF (Cont.)
Use Case SNMP NETCONF
Get collection of status fields Yes Yes (bulk transfer
up to 10x faster)
Set collection of configuration fields Yes, up to 64kB Yes
Set configuration fields in transaction No Yes
Transactions across multiple network elements No Yes
Invoke administrative actions Well… Yes
Send event notifications Yes Yes, connected
Backup and restore configuration Usually not Yes
Secure protocol v3 Yes
Test configuration before final commit No Yes
Service Activation No Yes
The final significant advantage of NETCONF over SNMP is that it is oriented at service management (i.e.
and atom of configuration is a service and not an individual attribute).
Four Properties That Define a Transaction: ACID
Atomicity:
 Transactions are indivisible, all-or-nothing
Consistency:
 Transactions are all-at-once
 No internal order inside a transaction, it is a set of changes, not a sequence
 Implies that { create A, create B } and { create B, create A } are identical
 Systems behaving differently with respect to the sequence are not transactional
Independence:
 Parallel transactions do not interfere with each other
 Transactions appear to happen always-in-sequence
Durability:
 Persistent configuration even in the case of a fail-over, failure, restart, etc.
Atomicity
Transactions are indivisible and are implemented using the "all-or-nothing" approach. If and individual
action fails, the entire transaction is reverted back to the previous state.
Consistency
Transactions are also implemented all at once. There is no internal order inside a transaction, it is a set of
changes, not a sequence (e.g. actions { create A, create B } and { create B, create A } are identical).
Independence
Parallel transactions do not interfere with each other and transactions appear to happen always-in-sequence.
Durability
Persistent configuration even in the case of a fail-over, failure, restart, etc.

Transactions: Order Independence
Transaction A Transaction B
Add route 55.66.0.0/24
⇔
Add interface eth5
over interface eth5
Add route 55.66.0.0/24

Add interface eth5
over interface eth5
 Configuration transactions are decoupled from their sequential execution

 Obviously, the order matters in the execution but it is not the manager’s concern
in a transactional system
One of the requirements for NETCONF is that the independent of internal order. The actual order of the
configuration commands may be important, but the order should not burden the management system.
Transactions: Configuration Backup and Restore
Backup Restore
Read the configuration Send the saved configuration
 Manager does not need to know which  No need to sort data
elements are configuration  All-or-nothing semantics
Save result to a file  No PDU size limit
 Human readable XML file
 Use diff and other XML processing tools
 Edit file, if desired
Transactions should provide for simple bulk configuration operation such as backing up the configuration or
restoring from backup. The configuration should be available in a text format (e.g. XML encoded).

Transaction: Service Activation
OSS computes configuration OSS sends configuration change

changes to send to network: to all concerned devices in a
Operator creates new service in  Some IPTV server edits network wide transaction:
OSS GUI:  Three routers  No need to sort data
 IPTV service, HD quality  Two firewalls  All-or-nothing semantics
 Addition to across all devices
inventory/billing system  Each device validates
 Operator is only concerned with the service parameters

 OSS takes care of everything else
 OSS has improved reliability in configuration deployment
 Automatically revert to last known good state if any item of the transaction fails
The main goal of transaction-based network-wide management is to make the configuration building blocks
transparent and only expose the service parameters to the management system and operator. The operations
support system (OSS) takes care of takes care of the rest by mapping the service model to individual device
configuration snippets that are part of the same transaction.
The process of configuration deployment may go through several validation steps (on OSS, on device before
deployment, on device after deployment). A transaction will revert to a previous state if any of the individual
components failed to deploy.
Transactions
Network-wide transactions is the most important leap in

network management technology since SNMP.
No error recovery and sequencing tasks are needed on

the manager side.
This is usually more than half the cost in a mature

system; more than the entire cost of the managed
devices.
Network-wide transactions are the most important leap in network management technology since SNMP. No
error recovery and sequencing tasks are needed on the manager side. This is usually more than half the cost
in a mature system; more than the entire cost of the managed devices.

NETCONF Operation
This topic explains the main NETCONF concepts.
NETCONF Transport
Transaction A  NETCONF messages are encoded in XML

Add interface eth5  NETCONF defines operations commands and
message types to control configuration and
Add route 55.66.0.0/24
over interface eth5 notification opeartions
 NETCONF messages are encrypted by SSH
 NETCONF over SOAP, BEEP (both now deprecated) and TLS
SSH
are also defined, but not used
 SSH provides authentication, integrity and confidentiality
 NETCONF is using TCP

TCP  No need for manager to request resends
 Efficient use of the medium
The figure illustrates the important three components that comprise a NETCONF session:
 NETCONF that encodes messages using XML.
 SSH to provide secure communication between client and server.
 TCP to provide reliability to the communications between client and server.
NETCONF Extensibility
<hello>
 Version negotiation
<capabilities>
<capability>urn:ietf:params:netconf:base:1.1</capability>
 Capability negotiation
<capability>urn:ietf:params:netconf:capability:writable-running:1.0</capability>
<capability>urn:ietf:params:netconf:capability:candidate:1.0</capability>
<capability>urn:ietf:params:netconf:capability:confirmed-commit:1.0</capability>
 Supported subset of
<capability>urn:ietf:params:netconf:capability:xpath:1.0</capability> capabilities used
<capability>urn:ietf:params:netconf:capability:validate:1.0</capability>
<capability>urn:ietf:params:netconf:capability:rollback-on-error:1.0</capability>  Extensions go in
<capability>http://tail-f.com/ns/netconf/with-defaults/1.0</capability>
<capability>http://tail-f.com/ns/netconf/actions/1.0</capability>
separate XML
Device namespaces, which
Manager <capability>http://tail-f.com/ns/netconf/commit/1.0</capability>
(server)
(client) <capability>http://tail-f.com/ns/example/dhcpd?module=dhcpd</capability>
makes it easier to build
<capability> ... </capability>
</capabilities> backward compatible
<hello> management
<hello>
<capabilities>
<capability>urn:ietf:params:netconf:base:1.1</capability>
<capability>urn:ietf:params:netconf:capability:candidate:1.0</capability>
<capability> ... </capability>
</capabilities>
</hello>
When a NETCONF Manager connects to a NETCONF Server (Device), they say<hello>.

The contents of the <hello> message declares which NETCONF Capabilities each party is capable of.
 Some capabilities are defined by the base NETCONF specification.
 Each Yang Data model the device knows is also a capability.
 Other specifications (standards body or proprietary) also define capabilities.
By declaring support for a capability in <hello>, the manager will know which operations it can submit to the
Device.
Extensions go in separate XML namespaces, which makes it easier to build backwards and forwards
compatible management applications.

NETCONF Configuration Data Stores
Startup Running Candidate Files … / URLs …
 There may be a number of named configuration data stores:

 Mandatory: Running
 Optional: Startup, Candidate
 Other: …
 Each data store may hold a full copy of the configuration
 Running may or may not be directly writable (:writable-running)
 Need to copy from other stores if not directly writable
There may be a number of configuration data stores with different capabilities.

 Named configuration stores; each data store may hold a full copy of the configuration
 Running datastore is mandatory; Startup and Candidate optional (capabilities :startup, :candidate)
 Running may or may not be directly writable (:writable-running); need to copy from other stores if not
directly writable
NETCONF Network-Wide Transactions
NETCONF
Candidate Candidate Candidate Candidate Candidate
 Candidate data stores enable data-wide transactions:

 Send configuration changes to all participating devices
 Commit candidates if all participating devices successfully validate changes
The figure illustrates how configurations that are part of a transaction are sent to all participating devices.
Each device will use at least one verification step in order to determine if the configuration can be
successfully applied.
Candidate data stores enable the final committing of the configurations on all devices if all devices reported
that the configuration was successfully validated. In case one device reports a failure, the configuration will
not be committed on any device.

NETCONF Base Operations
<get>
<get-config>  A powerful set of operations
<edit-config>
<test-option> (:validate 1.1)  Each operation can contain
<error-option>
<operation> (e.g. merge, replace, delete) additional attributes
<copy-config>
<commit> (:candidate, :confirmed)  Some operations are only
<discard-changes> (:candidate)
<cancel-commit> (:candidate) available if required capability is
<delete-config>
<lock> supported
<unlock>
<close-session>
<kill-session>
The NETCONF protocol provides a small set of low-level operations to manage device configurations and
retrieve device state information. The base protocol provides operations to retrieve, configure, copy, and
delete configuration datastores. Additional operations are provided, based on the capabilities advertised by
the device.
The base protocol includes the following protocol operations:
 get
 get-config
 edit-config
 copy-config
 delete-config
 lock
 unlock
 close-session
 kill-session
Refer to section 7 of RFC 6241 for more information about NETCONF commands.
NETCONF Capabilities
RFC 6241 Optional Other Standard NETCONF Proprietary NETCONF

Capabilities Capabilities Capabilities
:writable-running :notification, :interleave (RFC 5277) :actions (tail-f)
:candidate :partial-lock (RFC 5717) :inactive (tail-f)
:confirmed-commit :with-defaults (RFC 6243)
:rollback-on-error :ietf-netconf-monitoring (RFC 6022)
:validate
:startup  Base capabilities per version (1.0 or 1.1 currently)
:url (scheme=http, ftp, file)
 Optional capabilities (RFC 6241 or other RFCs)
:xpath (filters)
 Proprietary capabilities (e.g. Tail-F)
A NETCONF capability is a set of functionality that supplements the base NETCONF specification. The
capability is identified by a uniform resource identifier (URI) [RFC3986].
Capabilities augment the base operations of the device, describing both additional operations and the content
allowed inside operations. The client can discover the server's capabilities and use any additional operations,
parameters, and content defined by those capabilities.
The capability definition might name one or more dependent capabilities. To support a capability, the server
MUST support any capabilities upon which it depends.
Additional capabilities can be defined at any time in external documents, allowing the set of capabilities to
expand over time. Standards bodies can define standardized capabilities, and implementations can define
proprietary ones. A capability URI must sufficiently distinguish the naming authority to avoid naming
collisions.

NETCONF Example
<rpc xmlns="urn:ietf:params:xml:ns:netconf:base:1.1” message-id="5">
<edit-config xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0">
Prepare
<target> candidate
<candidate/>
1. </target> configuration
<test-option>test-then-set</test-option>
<error-option>rollback-on-error</error-option>
<config>
<interface xmlns=”urn:ietf:params:xml:ns:yang:ietf-interfaces">
<name>Ethernet0/0</name>
<ipv4-address>192.168.5.10</ipv4-address> Device
Manager <macaddr>aa:bb:cc:dd:ee:ff</macaddr> (server)
(client) </interface>
</config>
</edit-config>
</rpc> Acknowledge
receipt
<rpc-reply xmlns="urn:ietf:params:xml:ns:netconf:base:1.1“ message-id="5">
<ok/> 2.
</rpc-reply>
The above example illustrates the setting of the configuration:

 The first step in the process is the sending of the candidate configuration by the NETCONF client
(management server).
 The NETCONF server (device) responds by acknowledging the receipt of the candidate configuration.
 (continued on next page)
NETCONF Example (Cont.) Validate
configuration
3.
(i.e. commit)
<validate>
<source>
<candidate/>
</source>
</validate>
</rpc> Device
Manager (server)
(client)
<rpc-reply xmlns="urn:ietf:params:xml:ns:netconf:base:1.1“ message-id=“6”>
<ok/>
</rpc-reply> 4.

Permanently
<commit> activate
5. <confirmed/>
</commit> configuration (i.e.
</rpc> confirm commit)
<rpc-reply xmlns="urn:ietf:params:xml:ns:netconf:base:1.1“ message-id=“7”>
<ok/> 6.
</rpc-reply>
Continuation of NETCONF configuration process from previous page:

 In the second step, the NETCON client asks to validate the configuration.
 The device respond by acknowledging the receipt of the request and indicating that there is no error with
the validation.
 In the last step, the client asks the device to make the candidate configuration permanently active (this is
similar to Cisco IOS XR confirmed commit).
If the device validates the configuration it will inform the server. A transaction may consist of multiple
devices being configured. If all devices successfully validate the configuration, the transaction is deemed
successful.
If any of the devices reports an error, the Cisco Network Services Orchestrator (NSO) will have to revert the
configurations by not performing the final commit. In the example above, the device reported success so the
NSO sends the final commit which puts the configuration into production.

Common NETCONF Use Cases
 Network-wide transactions
 Applying and testing a configuration
 Testing and rejecting a configuration
 Rollback when device goes down
 Transactions requiring all devices to be up
 Backlogging transactions
 Synchronizing
The above list provides some most common usage scenarios for NETCONF:
 Network-wide transactions with candidate configurations for better reliability.
 Applying and testing a configuration.
 Testing and rejecting a configuration.
 Rollback of configuration is a device goes down.
 Transactions requiring all devices to be up.
 Backlogging transactions for delayed deployment.
 Synchronizing configurations between client and server.
Summary
 IETF standards and recommendations:
 RFC 6020 YANG Base Specification
 RFC 6087 Guidelines for YANG Authors and Reviewers
 RFC 6110 Mapping YANG and Validating NETCONF Content
 RFC 6244 NETCONF+Yang Architectural Overview
 RFC 6643 Translation of SMIv2 MIBs to YANG
 RFC 6991 Common Yang Data Types
 RFC 7223 YANG Module for Interface Management
 RFC 7224 YANG Module for Interface Types
 Other useful sources:
 https://datatracker.ietf.org/wg/netmod/charter/
 https://www.ietf.org/iesg/directorate/yang-doctors.html
 http://www.yang-central.org/
 http://www.netconfcentral.org/
References

Lesson 1-4
YANG Overview
Overview
This lesson provides an overview of the YANG data modelling language. It is the basis for
Cisco Network Services Orchestrator's service modelling.
Objectives
 Understand the purpose and value of YANG
 Learn YANG fundamentals
Introduction to YANG
This topic introduces the YANG modeling language and shows how it is used when
orchestrating network services.
YANG
"YANG is a data modeling language used to model configuration and state data manipulated by the
Network Configuration Protocol (NETCONF), NETCONF remote procedure calls, and NETCONF
notifications. YANG is used to model the operations and content layers of NETCONF"
IETF RFC 6020
Service Models The YANG models describe

The NETCONF protocol allows a everything there is to …
manager to set configuration, YANG  Configure
query configuration and state and  Monitor
execute actions on the device NETCONF  Admin actions
(similar to SNMP).  Notifications
… for each device type and
version (similar to MIBs).
Device 3: Device 4: Device 9:

Vendor A Vendor B Vendor W
Model Y Model Z Model T
Note! NETCONF is not the only Version Version Version F
protocol. NSO also uses NEDs. 1.3 9.5
The figure illustrates how YANG sits on top of the Network Configuration Protocol (NETCONF) to translate
a more device-oriented language (NETCONF) to a more human-readable language – YANG. While
NETCONF provides a standardized way of communicating with different types of devices, YANG provides
a framework for describing configurations using a syntax and semantics that is closer to human languages.
The YANG data modelling language is defined by IETF RFC 6020 and is augmented by a number of other
RFCs such as:
 RFC-7317 YANG for System Management
 RFC-7277 YANG for IP Management
 RFC-7224 IANA Intf. Type YANG Module
 RFC-7223 YANG for Intf. Management
 RFC-6991 Common YANG Data Types
 RFC-6536 NETCONF Access Control
 RFC-6470 NETCONF Base Notifications
 RFC-6244 Architecture for Network Management Using NETCONF and YANG
 RFC-6087 Guidelines for YANG Authors
 RFC-6022 YANG for NETCONF Monitoring
The figure illustrates the IETF's efforts to standardize management by describing two major components
through the above RFCs. NSO, however, provides a powerful set of Network Element Drivers (NEDs) that
can be used to manage virtually any type of device, even or especially if they do not support NETCONF
(yet). NEDs provide a very flexible addition which is also implemented using YANG.
YANG Characteristics
 Designed for readability

 Uses UTF-8 encoding to support international character sets
 Simplicity enables fast service model development
 Modularity and hierarchy enable reuse of code
Some of the main advantages of using YANG are:

 It was designed for readability (e.g. XML is much more difficult to read without dedicated XML editor
software).
 It was designed to support any international character set by using UTF-8. A number of management
products are limited to using the ASCII character set which may be detrimental to the management of
services where the support for languages using different character sets is required. UTF-8 is the
predominant choice today for providing such functionality.
 It provides similar development options as typical programming languages in order to facilitate code
modularity, hierarchy, reuse, etc.
 It was designed with simplicity in mind in order to make it easy to learn and allow fast development of
data models.

YANG Model Hierarchy and Modularity
acme.yang sirius.yang
module acme { module sirius {
namespace A; namespace B;  Imported fragments are just
referenced, not included
import sirius; ...
 Used to group reusable definitions
include aurora; } that can be reused by many other
include orion; modules
 Similar to libraries in programing
...
languages
}
include include
 Useful to split large modules into smaller
more manageable files
orion.yang aurora.yang
submodule orion { submodule aurora {
 Submodule can never be included in any
other module
... ...
 Module and submodules share the same
} } namespace
Modules and Submodules

The module is the base unit of definition in YANG. A module defines a single data model. A module can
define a complete, cohesive model, or augment an existing data model with additional nodes. Submodules
are partial modules that contribute definitions to a module. A module may include any number of
submodules, but each submodule may belong to only one module. The names of all standard modules and
submodules MUST be unique. Developers of enterprise modules are RECOMMENDED to choose names for
their modules that will have a low probability of colliding with standard or other enterprise modules, e.g., by
using the enterprise or organization name as a prefix for the module name.
A module uses the "include" statement to include its submodules, and the "import" statement to reference
external modules. Similarly, a submodule uses the "import" statement to reference other modules, and uses
the "include" statement to reference other submodules within its module. A module or submodule MUST
NOT include submodules from other modules, and a submodule MUST NOT import its own module.
The import and include statements are used to make definitions available to other modules and submodules:
 For a module or submodule to reference definitions in an external module, the external module MUST
be imported.
 For a module to reference definitions in one of its submodules, the module MUST include the
submodule.
 For a submodule to reference definitions in a second submodule of the same module, the first
submodule MUST include the second submodule.
There MUST NOT be any circular chains of imports or includes. For example, if submodule "a" includes
submodule "b", "b" cannot include "a". When a definition in an external module is referenced, a locally
defined prefix MUST be used, followed by ":", and then the external identifier. References to definitions in
the local module MAY use the prefix notation. Since built-in data types do not belong to any module and
have no prefix, references to built-in data types (e.g., int32) cannot use the prefix notation.
YANG Module Structure
acme.yang
module acme {
namespace "http://acme.example.com/module";
prefix acme; Header Information
organization "ACME Inc.";
description "Module describing the ACME products";
revision 2007-06-09 { description "Initial revision."; } Revision Information
import ietf-yang-types { prefix yang; }
include acme-system; Imports & Includes
typedef percentage-type {
type uint8 { range "1..100"; } Type Definitions
}
grouping ifdata {
leaf ipv4-address {
type inet:ipv4-address;
}
leaf ipv4-mask { Reusable Node
type inet:ipv4-address; Declarations
}
}
Each module must have the following sections:

 Module name that should preferably be the same as the module's file name (case sensitive equality
between module name and file name prevents a warning message when validating a module).
 Header information describes the module and gives information about the module itself:
— Namespace (mandatory): defines the Uniform Resource Identifier (URI) of XML namespace.
— Prefix (mandatory): the prefix statement is used to define the prefix associated with the module
and its namespace. The prefix statement's argument is the prefix string that is used as a prefix to
access a module.
— Organization, contact (optional): describes the module origin (e.g. company, author).
— Description (optional): provides a description of the module (what it is, what it does, etc.).
 Revision information: provides versioning of the module and facilitates the importing of modules
based on revisions.
 Imports and includes: the import and include statements are used to make definitions available to other
modules and submodules
 Type definitions: in addition to built-in data types, custom types can be defined and later used in the
data models.
 Reusable node declarations: in addition to type definitions, a more complex set of YANG code can be
defined and later reused.
 (list continued on next page)

YANG Module Structure (Cont.)
list loopback-interface {
key "Loopback";
leaf Loopback {
type string; Configuration & Operational
} Data Declarations
uses ifdata;
}
notification link-failure {
description "A link failure has been detected";
leaf if-name { type string; }
leaf if-admin-status { type uint8; }
}
rpc clear-interface { Action (RPC) &

input { Notification Declarations
leaf interface-name { type string; }
}
output {
leaf status { type string; }
}
}
} End of Module File
 (list continued from previous page)

 Configuration and operational data declarations: this is the main part of the module where the actual
data model is defined.
 Action (RPC) and notification declarations: defines NETCONF Remote Procedure Calls (RPC) and
notifications to be used within the module.
Basic YANG Statements Defining Data Nodes
YANG Programming Description

Equivalent
Leaf Variable Contains a single value of a specific type
Leaf-List Array Contains a list of values of the same type
Container Record Contains a single structure containing zero or more values or other
statements (hierarchy)
List Array of Records Contains a list of zero or more sets of values and other statements
(hierarchy)
The table lists the most basic and common statements used when building a data model:
 The leaf statement represents the simplest atom of information – single value of a specific type. This is
similar to scalar variables in programming languages.
 The leaf-list statement represents a list of values (zero or more) of the same type. This is similar to an
array of scalar variables in programming languages.
 The container statement represents a more relaxed structure that can contain a variety of other types of
statements. The container itself does not hold any value and hence does not have any type. This is
similar to a record definition in programming languages.
 The list statement represents a list of records (zero or more). This is similar to an array of records in
programming languages.

YANG Model Statements and Hierarchy
Container
Container
Leaf-List
Leaf
Container  Leaf: single value of a defined type

List
 Leaf-list: multiple values of the same type
Leaf
 List: multiple records containing at least one
Container Leaf Leaf Leaf-Ref
leaf (key) and an arbitrary hierarchy of other
statements
Leaf
 Container: groups other statements; has no
value
Leaf  Leafref: is a reference to another leaf
The figure above illustrates the hierarchy of a sample YANG model and the properties of individual
statements (data type, multiplicity).
YANG Model Statements and Hierarchy Example
container car {
Statement characteristics:
container v8_engine {
leaf-list cylinder-arrangement {  Name
type string;
max-elements 8;  Type (e.g. string, uint32)
}
 Constraints:
container other-parts {
 min-elements
list per-cylinder-parts {
 max-elements
leaf piston-diameter {
type uint32;  range
range "2000..9000";
}  key/unique
container valves {  leafref
leaf number { … }
list position { … }  must
…
}  when
}
 Statement content is enclosed within curly
}
brackets
}
}  Each sub-statement is terminated by semicolon
The figure illustrates the same example as on the previous page with the addition of YANG code that
represents a fictitious data model to describe a V8 engine and its parts.
The example illustrates the use of the previously described statements with the addition of data types and
syntax:
 Each statement is identified by a case-sensitive name.
 Each basic statement must be terminated by a semicolon.
 A complex statements that contains other statements, modifiers, constraints or any other type of
substatement, is enclosed within curly brackets.
 Each leaf and leaf-list statement require the definition of the data type using the type keyword.
Additionally, data types can be constrained using keywords, such as range, max-elements, min-
elements, etc.

Other Representations of YANG
A YANG module can be translated into other representations.
Other YANG Representations
YIN
 XML representation of YANG
 Enables developers to use the rich set of XML-based tools for data
filtering and validation, automated generation of code and documentation,
and other tasks
ASCII tree
 Enables visualization of the data model hierarchy in a terminal window
HTML collapsible tree
 Enables visualization and browsing of the data model hierarchy in a web
browser
The YANG and YIN formats contain equivalent information using different notations. The YIN notation
enables developers to represent YANG data models in XML and therefore use the rich set of XML-based
tools for data filtering and validation, automated generation of code and documentation, and other tasks.
Tools like Extensible Stylesheet Language Transformations (XSLT) or XML validators can be utilized.
The mapping between YANG and YIN does not modify the information content of the model.
There is a one-to-one correspondence between YANG keywords and YIN elements. The local name of a
YIN element is identical to the corresponding YANG keyword. This means, in particular, that the document
element (root) of a YIN document is always <module> or <submodule>.
Additionally, it may be useful to convert a YANG model to a hierarchical representation such as a
collapsible HTML version that can be explored using a web browser, or a text version that can be inspected
when using a command line.
Converting from YANG to Other Formats
 Use the pyang tool for validation, conversion or visualization of YANG:
 Convert to YIN: pyang -f yin
 Convert to a collapsible tree in HTML: pyang -f jstree
 Convert to an ASCII tree: pyang -f tree
list loopback-interface { <list name="loopback-interface"> +--rw loopback-interface*
key Loopback; <key value="Loopback"/> [Loopback]
unique ip-address; <unique tag="ip-address"/> +--rw Loopback string
<leaf name="Loopback"> +--rw ip-address? uint32
leaf Loopback { <type name="string"/>
type string; </leaf> Note! The input must be a valid
} <leaf name="ip-address">
<type name="uint32"/> module file. Below are just partial
leaf ip-address { </leaf> examples.
type uint32; </list>
}
}
A handy Python tool called pyang is available to perform the following three useful functions:
 Convert YANG to YIN (shown in the example above).
 Convert YANG to an HTML file that contains a collapsible tree representing the data model. This is
especially useful in large and complex models where a basic editor is no longer the best choice for
viewing and editing the YANG data model. In this case it is recommended to use a dedicated YANG
IDE that supports a collapsible tree view. Alternatively, you can use pyang to convert the YANG file to
an HTML file and view the collapsible data model tree using any browser that supports JavaScript.
 Convert YANG to a text file where the hierarchy is illustrated using ASCII characters (shown above).
The pyang tool supports many other operations (use pyang --help or man pyang to learn about them).

YANG Data Types
This topic describes the main data types used in the YANG modeling language.
YANG Data Types
 Built-in data types

 Derived data types:
 RFC-defined data types (RFC 6991)
 NSO-defined data types
 Custom data types
The YANG model can use the following sources for data types:
 Built-in data types: YANG has a set of built-in types, similar to those of many programming
languages, but with some differences due to special requirements from the management domain.
 RFC-defined data types: RFC 6991 defines additional data types described later.
 Custom data types: custom data types can be defined as part of the data model or they may be available
by importing other modules that contain additional data type definitions (e.g. Cisco NSO comes with a
set of additional data types that come in useful when describing device or service configurations).
YANG Supports a Number of Data Types
Built-in Types Derived Types
Name Description typedef my-base-int32-type {
type int32 {
int8/16/32/64 Integer range "1..4 | 10..20";
}
uint8/16/32/64 Unsigned integer }
decimal64 Non-integer
typedef derived-int32 {
string Unicode string type my-base-int32-type {
range "11..max";
enumeration Set of alternatives }
boolean True or false }
bits Boolean array typedef string255 {

type string {
binary Binary BLOB length "1..255";
}
leafref Reference
}
identityref Unique identity
typedef derived-str {
empty No value, void type string255 {
union Choice of member types length "11 | 42..max";
pattern "[0-9a-fA-F]*";
}
instance-identifier References a data tree node }
The following table lists the built-in data types as defined in RFC 6020.
Data Type Name Description
binary Any binary data
bits A set of bits or flags
Boolean true or "false"
decimal64 64-bit signed decimal number
Empty A leaf that does not have any value
enumeration Enumerated strings
Identityref A reference to an abstract identity
instance-identifier References a data tree node
int8 8-bit signed integer
leafref A reference to a leaf instance
string Human-readable string
uint8 8-bit unsigned integer
union Choice of member types
Custom or derived data types are created using the typedef keyword.

Common YANG Data Types (RFC 6991)
IETF YANG Types Using Types
Name Description import ietf-yang-types {
counter32 prefix yang;
non-negative 32-bit integer that monotonically increases
}
zero-based-counter32 a counter32 that has the defined initial value zero
counter64 non-negative 64-bit integer that monotonically increases
zero-based-counter64 a counter64 that has the defined initial value zero
gauge32 non-negative integer, which may increase or decrease
gauge64 non-negative integer, which may increase or decrease
date-and-time ISO 8601 standard for representation of dates and times
phys-address colon-separated hexadecimal pairs (e.g. 1a:ba:da:ba:d0)
mac-address six colon-separated hexadecimal pairs (e.g. 1a:ba:da:ba:d0:00)
xpath1.0 XPATH 1.0 expression
hex-string colon-separated hexadecimal pairs of arbitrary length
uuid universally unique identifier (RFC 4122)
…
In addition to the built-in data types, you can import modules that contain additional data type definitions.
There are two standard modules that contain data types defined in RFC 6991:
 IETF YANG data types
 IETF Inet data types
The following table lists the YANG data types defined in RFC 6991:
counter32 Counter32 (SNMPv2-SMI)
zero-based-counter32 ZeroBasedCounter32 (RMON2-MIB)
counter64 Counter64 (SNMPv2-SMI)
zero-based-counter64 ZeroBasedCounter64 (HCNUM-TC)
gauge32 Gauge32 (SNMPv2-SMI)
gauge64 CounterBasedGauge64 (HCNUM-TC)
object-identifier -
object-identifier-128 OBJECT IDENTIFIER
yang-identifier -
date-and-time -
timeticks TimeTicks (SNMPv2-SMI)
timestamp TimeStamp (SNMPv2-TC)
phys-address PhysAddress (SNMPv2-TC)
mac-address MacAddress (SNMPv2-TC)
xpath1.0 -
hex-string -
uuid -
dotted-quad -
Common YANG Data Types (RFC 6991) (Cont.)
IETF INET Types Using Types
Name Description import ietf-inet-types {
IP protocol version: 1=IPv4, 2=IPv6, 0=unknown
prefix inet;
ip-version
}
dscp Differentiated Services Code Point value: 0 to 63
ipv6-flow-label 32-bit integer in the range from 0 to 1048575
port-number 16-bit integer in the range from 0 to 65535
as-number 32-bit integer representing 2 or 4 octet BGP AS numbers

ip-address IPv4 or IPv6 address
ipv4-address IPv4 address (e.g. 10.1.2.3)
ipv6-address IPv6 address (e.g. fd85:b310:6513:194b::1)
ip-prefix IPv4 or IPv6 prefix
ipv4-prefix IPv4 prefix (e.g. 10.1.2.0/24)
ipv6-prefix IPv6 prefix (e.g. fd85:b310:6513:194b::/64)
domain-name DNS domain name
host IP address or DNS domain name
uri uniform resource identifier
…
The following table lists the Inet data types defined in RFC 6991:
ip-version InetVersion (INET-ADDRESS-MIB)
dscp Dscp (DIFFSERV-DSCP-TC)
ipv6-flow-label IPv6FlowLabel (IPV6-FLOW-LABEL-MIB)
port-number InetPortNumber (INET-ADDRESS-MIB)
as-number InetAutonomousSystemNumber (INET-ADDRESS-MIB)
ip-address IPv4 or IPv6 address
ipv4-address IPv4 address
ipv6-address IPv6 address
ip-address-no-zone -
ipv4-address-no-zone -
ipv6-address-no-zone -
ip-prefix -
ipv4-prefix -
ipv6-prefix -
domain-name -
host -
uri Uri (URI-TC-MIB)

Derived Type Restrictions typedef acl-num-type {
type int32 {
range
typedef "1..199 | 1300..2699";
acl-num-type {
Range: }
type
} int32 {
range "1..199 | 1300..2699";
 Applies to integer and decimal types }
}
typedef std-acl-num-type {
 "x .. y" type acl-num-type {
typedef std-acl-num-type {
range "min..99 | 1300..1999";
 "min .. x" type
} acl-num-type {
} range "min..99 | 1300..1999";
 "x .. max" }
}
typedef ext-acl-num-type {
 "x .. y | a .. b" type acl-num-type
typedef {
ext-acl-num-type {
range
type "100..199 |
acl-num-type { 2000..max";
} range "100..199 | 2000..max";
Length: } }
 Applies to string type }
typedef acl-name-type {
type string
typedef {
acl-name-type {
 Same syntax as with range length
type "1..50";
string {
pattern "[a-zA-Z][a-zA-Z0-9-_]*";
length "1..50";
Pattern: } pattern "[a-zA-Z][a-zA-Z0-9-_]*";
} }
 Applies to string type }
typedef std-acl-name-type { type acl-name-type; }
typedef std-acl-name-type
ext-acl-name-type { type acl-name-type; }
 Uses regular expressions as defined in typedef ext-acl-name-type { type acl-name-type; }
typedef const-type {
appendix F of XML Schema Part 2 typedef const-type
type decimal64 { {
type decimal64 { 4;
fraction-digits
fraction-digits
range "2.7182 ..4;
Fraction-digits: }
3.1415";
range "2.7182 .. 3.1415";
}
 Applies to decimal type }
}
Range
The range statement, which is an optional substatement to the type statement, takes as an argument a range
expression string. It is used to restrict integer and decimal built-in types, or types derived from those. A range
consists of an explicit value, or a lower-inclusive bound, two consecutive dots "..", and an upper-inclusive
bound. Multiple values or ranges can be given, separated by "|". If multiple values or ranges are given, they
all must be disjoint and must be in ascending order. If a range restriction is applied to an already range-
restricted type, the new restriction must be equal or more limiting, that is raising the lower bounds, reducing
the upper bounds, removing explicit values or ranges, or splitting ranges into multiple ranges with
intermediate gaps. Each explicit value and range boundary value given in the range expression must match
the type being restricted, or be one of the special values min or max. The min and max keywords mean the
minimum and maximum value accepted for the type being restricted, respectively.
More detail available in section 7.2.4 of RFC 6020.
Length
The length statement, which is an optional substatement to the type statement, takes as an argument a length
expression string. It is used to restrict the built-in type string, or types derived from string. A length
statement restricts the number of Unicode characters in the string. A length range consists of an explicit
value, or a lower bound, two consecutive dots "..", and an upper bound. Multiple values or ranges can be
given, separated by "|". Length-restricting values must not be negative. If multiple values or ranges are given,
they all must be disjoint and must be in ascending order. If a length restriction is applied to an already length-
restricted type, the new restriction must be equal or more limiting, that is, raising the lower bounds, reducing
the upper bounds, removing explicit length values or ranges, or splitting ranges into multiple ranges with
intermediate gaps. A length value is a non-negative integer, or one of the special values min or max. The
min and max mean the minimum and maximum length accepted for the type being restricted, respectively.
An implementation is not required to support a length value larger than 18446744073709551615.
Pattern
The pattern statement, which is an optional substatement to the type statement, takes as an argument a
regular expression string, as defined in [XSD-TYPES]. It is used to restrict the built-in type string, or types
derived from string, to values that match the pattern.
If the type has multiple pattern statements, the expressions are ANDed together, i.e., all such expressions
have to match. If a pattern restriction is applied to an already pattern-restricted type, values must match all
patterns in the base type, in addition to the new patterns.
More detail available in section 7.2.4 of RFC 6020 and http://www.w3.org/TR/2004/REC-xmlschema-2-
20041028/#regexs.
Fraction Digits
The fraction-digits statement, which is a substatement to the type statement, must be present if the type is
decimal64. It takes as an argument an integer between 1 and 18, inclusively. It controls the size of the
minimum difference between values of a decimal64 type, by restricting the value space to numbers that are
expressible as "i x 10^-n" where n is the fraction-digits argument.

Combined Derived Types
typedef intf-ip-addr-type {
Enumeration: type union {
type inet:ip-address;
 Defines a set of names type enumeration {
enum "none";
Union: enum "unnumbered";
enum "dhcp";
 Used to define a type with a combination of }
}
two or more other types }
typedef acl-id-type {
type union {
type acl-num-type;
type acl-name-type;
}
}
Enumeration
The enumeration built-in type represents values from a set of assigned names. An enumeration cannot be
restricted.
The enum statement, which is a substatement to the type statement, must be present if the type is
enumeration. It is repeatedly used to specify each assigned name of an enumeration type. It takes as an
argument a string which is the assigned name. The string must not be empty and must not have any leading
or trailing whitespace characters. The use of Unicode control codes should be avoided.
Union
The union built-in type represents a value that corresponds to one of its member types. When the type is
union, the type statement must be present. It is used to repeatedly specify each member type of the union. It
takes as an argument a string that is the name of a member type. A member type can be of any built-in or
derived type, except it must not be one of the built-in types empty or leafref. When a string representing a
union data type is validated, the string is validated against each member type, in the order they are specified
in the type statement, until a match is found. Any default value or units property defined in the member
types is not inherited by the union type.
YANG Types Example
// percentage type // DSCP type
typedef percentage-type { typedef dscp-type;
type uint8 { type union;
range "1..100"; type uint8 { range "0..63"; }
} type enumeration {
} enum af11;
enum af12;
// Weekday type enum af13;
typedef weekday-type { enum af21;
type enumeration { enum af22;
enum Mon; enum af23;
enum Tue; enum af31;
enum Wed; enum af32;
enum Thu; enum af33;
enum Fri; enum af41;
enum Sat; enum af42;
enum Sun; enum af43;
} enum cs1;
} enum cs2;
enum cs3;
// Hour & minute & optional second type enum cs4;
typedef hhmm-type { enum cs5;
type string { enum cs6;
pattern '([0-1]?[0-9]|2[0-4]):' + enum cs7;
'([0-5][0-9])(:[0-5][0-9])?'; enum default;
} enum dscp;
} enum ef;
enum precedence;
// Route Distinguisher AS:NUM or IP:NUM }
typedef rd-type { }
type string { }
pattern '((\d+)((\.\d+){3})?)\:\d+';
}
}
The example illustrates how custom data types can be created to serve the requirements of a service model.
The example contains the following data types:
 Percentage where the value is limited to a range between 0 and 100.
 Weekday definitions using abbreviations to three characters.
 Time format that can contain hours and minutes and optionally seconds.
 Route distinguisher type that can use IP-address-based or AS-number-based format.
 Differentiated Services Code Point (DSCP) that can use names or numbers to represent the 64 possible
values.

Basic YANG Statements
This section delves into more detail for each of the statements listed below.
Basic YANG Statements

Container
 Data node definitions:
 Leaf
 Leaf-List
 Container List 11 25 Leaf
 List
 Other statements: 11 22
 Leafref 11 Leaf-List 22 Leaf-List

 Grouping Key leaf
(list index)
1 3 7 5 8 3
The first four statements are used to model the data hierarchy and type. The leafref is used to link to data
elsewhere in the model and the grouping is used to create reusable chunks of code.
Data Model and Data Visualization
Data model: Sample data:
 YANG  XML:
<loopback-ipv4>
 XPath to reference data in the hierarchy: <loopback>1</loopback>
<ip-address>10.1.1.1</loopback>
/ loopback-ipv4 </loopback-ipv4>
/ loopback-ipv4 / loopback <loopback-ipv4>
/ loopback-ipv4 / ip-address <loopback>2</loopback>
<ip-address>10.2.2.2</loopback>
</loopback-ipv4>
 Graphic visualization of hierarchy and data
type:
 Table:
Leaf T Typedef 192.0.2.213 16772
198.51.100.22 19234
L Leaf-list G Grouping
203.0.113.89 22315
L List K Key Leaf
These methods are used throughout the course to
C Container R Leafref help with understanding of YANG data modeling.
The figure above describes the visual tools that are used throughout this course to help with the
understanding of the different YANG constructs:
 The graphic boxes provide the essential information about the type of statements. This method is useful
to visualize the hierarchy of the data model and the type of data.
 Alternatively, the data (model) hierarchy can be represented using XPath.
 A table is used to illustrate sample data that reflects the data model, data type and constraints.
 Alternatively, sample data can also be represented using XML.

Leaf
loopback XPath:
/ loopback
1
YANG (data model) XML (data)

leaf loopback { <loopback>1</loopback>
type int32 {
range "0..2147483647";
}
}
 Single value using a built-in or derived data type

 Zero or one instance
The leaf statement is used to define a leaf node in the schema tree. It takes one argument, which is an
identifier, followed by a block of substatements that holds detailed leaf information. A leaf node has a value,
but no child nodes in the data tree.
A leaf node exists in zero or one instances in the data tree. The leaf statement is used to define a scalar
variable of a particular built-in or derived type.
More detail is available in section 7.6 of RFC 6020.
Leaf Attributes
Attribute Description
Whether this leaf is a configurable value ("true") or operational value ("false"). Inherited from
config
parent container if not specified
default Specifies default value for this leaf. Implies that leaf is optional
mandatory Whether the leaf is mandatory ("true") or optional ("false")
must XPath constraint that will be enforced for this leaf
type The data type (and range etc) of this leaf
when Conditional leaf, only present if XPath expression is true
description Human readable definition and help text for this leaf
reference Human readable reference to some other element or spec
units Human readable unit specification (e.g. Hz, MB/s, ℉)
status Whether this leaf is "current", "deprecated" or "obsolete"
Attribute: config
The config statement takes as an argument the string true or false. If config is true, the definition represents
configuration. Data nodes representing configuration will be part of the reply to a <get-config> request, and
can be sent in a <copy-config> or <edit-config> request. If config is false, the definition represents state
data. Data nodes representing state data will be part of the reply to a <get>, but not to a <get-config>
request, and cannot be sent in a <copy-config> or <edit-config> request. If config is not specified, the
default is the same as the parent schema node's config value. If the parent node is a case node, the value is
the same as the case node's parent choice node. If the top node does not specify a config statement, the
default is true. If a node has config set to false, no node underneath it can have config set to true.
Attribute: default
The default statement, which is optional, takes as an argument a string that contains a default value for the
leaf. The value of the default statement must be valid according to the type specified in the leaf's type
statement.
Attribute: mandatory
The mandatory statement, which is optional, takes as an argument the string "true" or false, and puts a
constraint on valid data. If not specified, the default is false. If mandatory is true, the behavior of the
constraint depends on the type of the leaf's closest ancestor node in the schema tree that is not a non-presence
container.
Attribute: must
The must statement, which is optional, takes as an argument a string that contains an XPath expression
(discussed later). It is used to formally declare a constraint on valid data. When a datastore is validated, all
must constraints are conceptually evaluated once for each data node in the data tree, and for all leafs with
default values in use. If a data node does not exist in the data tree, and it does not have a default value, its
must statements are not evaluated. All such constraints must evaluate to true for the data to be valid.
Attribute: type
The data type as described earlier (built-in or derived).

Attribute: when
The when statement makes its parent data definition statement conditional. The node defined by the parent
data definition statement is only valid when the condition specified by the when statement is satisfied. The
statement's argument is an XPath expression (discussed later), which is used to formally specify this
condition. If the XPath expression conceptually evaluates to true for a particular instance, then the node
defined by the parent data definition statement is valid; otherwise, it is not.
Attribute: description
The description statement takes as an argument a string that contains a human-readable textual description
of this definition. The text is provided in a language (or languages) chosen by the module developer; for the
sake of interoperability, it is recommended to choose a language that is widely understood among the
community of network administrators who will use the module.
Attribute: reference
The reference statement takes as an argument a string that is used to specify a textual cross-reference to an
external document, either another module that defines related management information, or a document that
provides additional information relevant to this definition.
Attribute: units
The units statement, which is optional, takes as an argument a string that contains a textual definition of the
units associated with the type.
Attribute: status
The status statement takes as an argument one of the strings current, deprecated, or obsolete. The
argument current means that the definition is current and valid. The argument deprecated indicates an
obsolete definition, but it permits new/continued implementation in order to foster interoperability with
older/existing implementations. The argument obsolete means the definition is obsolete and should not be
implemented and/or can be removed from implementations. If no status is specified, the default is current.
If a definition is current, it must not reference a deprecated or obsolete definition within the same module. If
a definition is deprecated, it must not reference an obsolete definition within the same module.
Leaf-List
L loopback
XPath:
1 / loopback
2
101
102

leaf-list loopback { <loopback>1</loopback>
type int32 { <loopback>2</loopback>
range "0..2147483647"; <loopback>101</loopback>
} <loopback>102</loopback>
}
 Unique values using a single built-in or derived data type

 Zero or more instances
Where the leaf statement is used to define a simple scalar variable of a particular type, the leaf-list statement
is used to define an array of a particular type. The leaf-list statement takes one argument, which is an
identifier, followed by a block of substatements that holds detailed leaf-list information. The values in a leaf-
list must be unique.
In the example above, we see a list of leaf values of the type int32 which are limited to a range between 0
and 2147483647. These are the valid number in Cisco IOS to number loopback interfaces. The table
illustrates four loopback numbers – 1, 2, 101 and 102, which are also shown in XML format.
More detail available in section 7.7 of RFC 6020.

Container
C loopback-ipv4 XPath:
/ loopback-ipv4
loopback ip-address / loopback-ipv4 / loopback
/ loopback-ipv4 / ip-address
1 10.1.1.1

container loopback-ipv4 { <loopback-ipv4>
leaf loopback { <loopback>1</loopback>
type int32 { <ip-address>10.1.1.1</loopback>
range "0..2147483647"; </loopback-ipv4>
}
}
leaf ip-address {
type inet:ipv4-address
}
}
 Used to group one or more other statements

 Has no data type by itself
 May have an implicit meaning
The container statement is used to define an interior data node in the schema tree. It takes one argument,
which is an identifier, followed by a block of substatements that holds detailed container information. A
container node does not have a value, but it has a list of child nodes in the data tree. The child nodes are
defined in the container's substatements.
In the example we see an expansion to the previous example where we define two parameters to represent a
loopback interface:
 Loopback interface number
 Loopback interface's IP address
The table shows one instance of the container that describes loopback1 having IP address 10.1.1.1.
List
L loopback-ipv4 XPath:
/ loopback-ipv4
K loopback ip-address / loopback-ipv4 / loopback
/ loopback-ipv4 / ip-address
1 10.1.1.1
2 10.2.2.2
list loopback-ipv4 { <loopback-ipv4>
key loopback; <loopback>1</loopback>
unique ip-address;
leaf loopback { <ip-address>10.1.1.1</loopback>
type int32 { </loopback-ipv4>
range "0..2147483647"; <loopback-ipv4>
} <loopback>2</loopback>
} <ip-address>10.2.2.2</loopback>
leaf ip-address { </loopback-ipv4>
type inet:ipv4-address
}
}
 Contains one or more substatements

 Requires one unique identifier (key)
 Zero or more instances
The list statement is used to define an interior data node in the schema tree. A list node may exist in multiple
instances in the data tree. Each such instance is known as a list entry. The list statement takes one argument,
which is an identifier, followed by a block of substatements that holds detailed list information. A list entry is
uniquely identified by the values of the list's keys, if defined.
The key statement, which must be present if the list represents configuration, and may be present otherwise,
takes as an argument a string that specifies a space-separated list of leaf identifiers of this list. A leaf
identifier must not appear more than once in the key. Each such leaf identifier must refer to a child leaf of
the list. The leafs can be defined directly in substatements to the list, or in groupings used in the list.
The combined values of all the leafs specified in the key are used to uniquely identify a list entry. All key
leafs must be given values when a list entry is created. Thus, any default values in the key leafs or their types
are ignored. It also implies that any mandatory statement in the key leafs are ignored.
A leaf that is part of the key can be of any built-in or derived type, except it must not be the built-in type
empty.
The example above illustrates a similar setup as in the previous example using the container statement. This
time the list statement enables many instances of loopback data where uniqueness only requires the loopback
number to be unique (i.e. IP addresses do not have to be unique).

List: Single Key
L user
K name uid full-name class

yang 1010 Yan Goode admin
hawk 1152 Ron Hawk oper
ling 1202 Lin Grossman viewer
XPath:
/ user [name='yang'] / name = yang list user {
/ user [name='yang'] / uid = 1010 key name;
/ user [name='yang'] / full-name = Yan Goode ...
/ user [name='yang'] / class = admin }
 The key refers to a leaf

 The key values must be unique
The example illustrates the usage of the key statement to select the leaf that is used as the unique identifier
for each list entry.
The XPath example shows how data can be referenced using the key values.
List: Combined Key
L route
K prefix K length next-hop metric

192.0.2.0 24 10.100.1.2 20
198.51.100.0 24 192.168.31.5 40
203.0.113.0 24 172.31.11.1 50
XPath:
/ user [prefix='198.51.100.0'][length='24'] / next-hop = 192.168.31.5
/ user [prefix='198.51.100.0'][length='24'] / metric = 40
list user {
 Keys refer to leaf statements key "prefix length";
...
 Key combinations must be unique }
This example shows how key combinations can be used define more complex list entry identifiers. In the
example it is required for the prefix and prefix length combination to be unique.

List Keys and Uniqueness Restrictions
list app {
key "address";
 At least one key is required: leaf address { type inet:ipv4-address; }
Each app uses a unique address.
leaf port { type uint16; } One instance can serve multiple
 key "leaf1"; leaf instance { type uint16; } apps. Ports can be reused.
}
 A combined key can be used: list app {
key "address";
 key "leaf1 [leaf2 …]"; unique "port instance";
leaf address { type inet:ipv4-address; } Each app uses a unique address.
leaf port { type uint16; }}
 Other attributes can also leaf instance { type uint16; }
One instance can serve multiple
} apps but not on the same port.
require uniqueness:
list app {
Unique combination of attributes: key "address port";
leaf address { type inet:ipv4-address; }
 unique "leaf1 [leaf2 …]"; leaf port { type uint16; }
Each app uses a unique
leaf instance { type uint16; }
…]";or } address/port pair. One instance
Individually unique attributes: list app { can serve multiple apps.
key "address";
 unique ""leaf1"; unique "port";
unique "instance";
 unique ""leaf2"; leaf address { type inet:ipv4-address; } Each app uses a unique address,
leaf port { type uint16; } port and instance.
leaf instance { type uint16; }
}
List Attribute: key

The key statement, which must be present if the list represents configuration, and may be present otherwise,
takes as an argument a string that specifies a space-separated list of leaf identifiers of this list. A leaf
identifier must not appear more than once in the key. Each such leaf identifier must refer to a child leaf of the
list. The leafs can be defined directly in substatements to the list, or in groupings used in the list. The
combined values of all the leafs specified in the key are used to uniquely identify a list entry. All key leafs
must be given values when a list entry is created. Thus, any default values in the key leafs or their types are
ignored. It also implies that any mandatory statement in the key leafs are ignored. A leaf that is part of the
key can be of any built-in or derived type, except it must not be the built-in type empty.
List Attribute: unique
The unique statement is used to put constraints on valid list entries. It takes as an argument a string that
contains a space- separated list of schema node identifiers, which must be given in the descendant form. Each
such schema node identifier must refer to a leaf. If one of the referenced leafs represents configuration data,
then all of the referenced leafs must represent configuration data. The unique constraint specifies that the
combined values of all the leaf instances specified in the argument string, including leafs with default values,
must be unique within all list entry instances in which all referenced leafs exist.
List and Leaf-List Attributes
Attribute Description
max-elements Max number of elements in a list
min-elements Min number of elements in a list
ordered-by List entries are sorted by "system" or "user".
System means elements are sorted in a natural order
(numerically, alphabetically, etc). User means the order
the operator entered them in is preserved.
leaf-list domain-search {
type string; system order user order
ordered-by user; cisco.com example.com
min-elements 1;
example.com
≠ cisco.com
max-elements 2;
}
List Attribute: max-elements

Max number of elements in list. If max-elements is not specified, there is no upper limit, i.e. "unbounded"
List Attribute: min-elements
Min number of elements in list. If min-elements is not specified, there is no lower limit, i.e. 0
List Attribute: ordered-by
List entries are sorted by "system" or "user". System means elements are sorted in a natural order
(numerically, alphabetically, etc.). User means the order the operator entered them in is preserved.
"ordered-by user" is meaningful when the order among the elements have significance, e.g. DNS server
search order or firewall rules.

Grouping
YANG (data model)
grouping app { G Grouping
leaf address {
type inet:ip-address;
} port
leaf port { address
type inet:port-number;
}
}
container http-server {
uses app {
refine port { C http-server
default 80;
}
} address port (default: 80)
}
container smtp-server { C smtp-server
uses app {
refine port { XPath:
default 25; address port (default: 25) / http-server
}
} / http-server / address
} 10.1.1.1 80 / http-server / port
10.1.2.1 25 / smtp-server
 Used to group YANG code for reuse / smtp-server / address
 Can be refined upon use / smtp-server / port
Groups of nodes can be assembled into reusable collections using the grouping statement. A grouping
defines a set of nodes that are instantiated with the uses statement.
The example illustrates the usage of a template (grouping) that is then used twice to describe the IP and TCP
port used for two services. Both services further refine the template by adding their default TCP porta values.
Leafref
L services C app
K ip K port R address R Port

192.0.2.213 16772 198.51.100.22 19234
198.51.100.22 19234
203.0.113.89 22315
list services { container app {
key "ip port" leaf address {
type leafref {
path "/services/ip";
leaf ip { }
type inet:ipv4-address; }
} leaf port {
type leafref {
leaf port { path "/services[ip=current()/../address]/port";
type uint16; }
}
} }
}
 Refer to a leaf or leaf-list elsewhere in the tree

 Inherits data type from referenced node
 The path keyword is used to match:
 the position in the tree
 the key(s) if referring to a leaf-list or leafs within a list (all key leafs must be referenced)
Data Type: leafref

The leafref type is used to reference a particular leaf instance in the data tree. The path substatement selects
a set of leaf instances, and the leafref value space is the set of values of these leaf instances. If the leaf with
the leafref type represents configuration data, the leaf it refers to must also represent configuration. Such a
leaf puts a constraint on valid data. All leafref nodes must reference existing leaf instances or leafs with
default values in use for the data to be valid. There must not be any circular chains of leafrefs.
The example illustrates how the app container references a specific value in the service list based on the
combined key using the ip and port leafs.

XPath Overview
This section provides an overview of some of the more used XPath capabilities with YANG
data modeling.
XPath
 XML Path Language defined by W3C

 Uses expressions to reference or extract parts of XML documents
 It also contains a number of useful functions for numbers and strings
 YANG uses XPath 1.0:
 Leafref: referencing Leaf or Leaf-List values in a data tree
 When and Must statements to add constraints to data model definitions
XPath is an XML Path Language defined by the W3C. It uses expressions to reference or extract parts of
XML documents. It also contains a number of useful functions for nodes, numbers and strings. Although
there are newer versions of XPath, YANG uses XPath version 1.0.
XPath is often used with Leafrefs when referencing Leaf or Leaf-List values elsewhere in the data tree, with
When and Must statements to add constraints to data model definitions.
XPath Expressions
 Expressions address an XML document and return a result that can be:
 Node set: multiple elements extracted from the XML document
 String: a single string element
 Number: a single number element
 Boolean: true or false
Expressions address an XML document and return a result that can be of one of the following type
categories:
 Node set: multiple elements extracted from the XML document
 String: a single string element
 Number: a single number element
 Boolean: true or false

XPath Examples: All Interface IP Addresses
XML Source Data XPath Expression XPath Result
<Loopback> <address>10.1.1.17</address>
<name>0</name> /*/ip/address/primary/address
<address>10.1.2.1</address>
<ip> or
<address> <address>10.1.2.5</address>
<primary> //primary/address <address>10.1.2.9</address>
<address>10.1.1.17</address> <address>10.1.2.13</address>
<mask>255.255.255.255</mask> <address>10.1.3.1</address>
</primary>
</address> <address>10.1.3.5</address>
</ip> <address>10.1.3.9</address>
</Loopback> <address>10.1.3.13</address>
<GigabitEthernet>
<name>0/1</name>
<ip>
<address>  Use directory-like path to address a hierarchy in the XML
<primary>
<address>10.1.2.1</address> document
<mask>255.255.255.252</mask>
</primary>
</address>  Use wildcard * to match any element at a given level
</ip>
</GigabitEthernet>
<GigabitEthernet>  Use // to match descendants at any level
<name>0/2</name>
<ip>
<address>
<primary>
...
The XPath example illustrates how an XPath expression (in the middle) can be used to process an XML
document (on the left) and extract the required result (on the right).
The example extracts IP addresses from all interfaces taken from the configuration of a Cisco IOS router
encoded using XML and according to the device model used by Cisco NSO for Cisco IOS devices.
The example makes use of the following characteristics of XPath expressions:
 Use directory-like path to address a hierarchy in the XML document
 Use wildcard * to match any element at a given level
 Use // to match descendants at any level
XPath Examples: All GE Interface IP Addresses
XML Source Data XPath Expression XPath Result
<Loopback> <address>10.1.2.1</address>
<name>0</name> <address>10.1.2.5</address>
<ip> //GigabitEthernet//primary/address
<address> <address>10.1.2.9</address>
<primary> <address>10.1.2.13</address>
<address>10.1.1.17</address> <address>10.1.3.1</address>
</primary>
</Loopback>
<GigabitEthernet>
<name>0/1</name>
<ip>  // is used as sort of wildcard for multiple levels in the
<address>
<primary> hierarchy between those of interest
<mask>255.255.255.252</mask>
</primary>
</address>
</ip>
</GigabitEthernet>
<GigabitEthernet>
<name>0/2</name>
<ip>
<address>
<primary>
...
The figure illustrates how we now only filter out the GigabitEthernet interface nodes thus not getting the
Loopback IP address in the result set.
The // expression is used as sort of wildcard for multiple levels in the hierarchy between those of interest (i.e.
GigabitEthernet and primary).

XPath Examples: All Module 0 GE IP Addresses
XML Source Data XPath Expression
<Loopback>
<name>0</name> //GigabitEthernet[starts-with(name,’0’)]//primary/address
<ip>
<address>
<primary> XPath Result
</primary> <address>10.1.2.5</address>
</Loopback>
<GigabitEthernet>
<name>0/1</name>
<ip>
<address>  Use [ expression ] to filter our the result node set based
<primary>
<address>10.1.2.1</address> on additional conditions
<mask>255.255.255.252</mask>
</primary>  Use XPath 1.0 functions to implement the required
</address>
</ip> conditions
</GigabitEthernet>
<GigabitEthernet>
<name>0/2</name>
<ip>
<address>
<primary>
...
The next example further filters the result by only displaying the IP addresses of GigabitEthernet interface
nodes which represent linecard 0 on the router. We can match those nodes of linecard 0 by looking for those
GigabitEthernet interface nodes that start with (0).
XPath Examples: First GE IP Addresses
XML Source Data XPath Expression
<Loopback> //GigabitEthernet[position()=1]//primary/address
<name>0</name>
<ip> or simply
<address>
<primary> //GigabitEthernet[1]//primary/address
<mask>255.255.255.255</mask>
</primary> XPath Result
</address>
</Loopback>
<GigabitEthernet>  Some other positioning options:
[1] <name>0/1</name>
<ip>  [position()=last()] or [last()]
<address>
<primary>  [position()>5]
<mask>255.255.255.252</mask>
</primary>
</address>
</ip>
</GigabitEthernet>
[2] <GigabitEthernet>
<name>0/2</name>
<ip>
<address>
<primary>
...
The example uses the index into the node set to extract a specific node or a range of nodes.

XPath 1.0 Functions
Category Function Description
Node count(node-set) Returns the number of nodes in the node set
position() Returns the context position index in the node set
last() Returns the index of the last node in the node set
id(node) Returns the node by name
String string(node-set) Returns the value of the first node as string
starts-with(string, prefix) Returns true if the string starts with the prefix
contains(string, substring) Returns true if the string contains the substring
string-length(string) Returns the length of string
Number number(node-set) Returns the value of the first node as number
sum(node-set) Return the sum of values converted to numbers
 Refer to https://www.w3.org/TR/xpath/ for a complete description of

XPath 1.0
The table lists a subset of available functions

Refer to https://www.w3.org/TR/xpath/ for a complete description of XPath 1.0
Additional NSO XPath Functions
Category Function Description
Node deref(node-set) Returns the node set pointed to by the provide node-set
parameter (e.g. if it is a leafref)
sort-by(node-set, string) Sorts the node set according to the secondary index
String string-compare(string1, string2) Returns -1, 0 or 1 based on string comparison
compare(exp1, exp2) Returns -1, 0 or 1 based on values returned by expressions
re-match(string, regexp) Evaluates the regexp regular expression against the string
Number min(node-set), max(node-set), Return the minimum, maximum or average value from the
avg(node-set) node set
band(number1, number2), Returns a binary OR, AND, XOR or negation of the
bor(number1, number2), parameters.
bxor(number1, number2),
bnot(number)
 Refer to https://www.w3.org/TR/xmlschema-2/#regexs for regular expression

description
This section describes XPath functions that can be used for example in "must" expressions in YANG
modules.
node-set deref(node-set)
The deref() function follows the reference defined by the first node in document order in the argument node-
set, and returns the nodes it refers to. If the first argument node is an instance-identifier, the function returns
a node-set that contains the single node that the instance identifier refers to, if it exists. If no such node exists,
an empty node-set is returned.
If the first argument node is a leafref, the function returns a node-set that contains the nodes that the leafref
refers to. If the first argument node is of any other type, an empty node-set is returned.
bool re-match(string, string)

The re-match() function returns true if the string in the first argument matches the regular expression in the
second argument; otherwise it returns false.
For example: re-match('1.22.333', '\d{1,3}\.\d{1,3}\.\d{1,3}') returns true. To count all logical interfaces
called eth0.number: count(/sys/ifc[re-match(name,'eth0\.\d+')]).
The regular expressions used are the XML Schema regular expressions, as specified by W3C in
http://www.w3.org/TR/xmlschema-2/#regexs. Note that this includes implicit anchoring of the regular
expression at the head and tail, i.e. if you want to match an interface that has a name that starts with 'eth' then
the regular expression must be 'eth.*'.
number string-compare(string,string)
The string-compare() function returns -1, 0, or 1 depending on whether the value of the string of the first
argument is respectively less than, equal to, or greater than the value of the string of the second argument.

number compare(Expression, Expression)
The compare() function returns -1, 0, or 1 depending on whether the value of the first argument is
respectively less than, equal to, or greater than the value of the second argument.
The expressions are evaluated in a special way: If they both are XPath constants they are compared using the
string-compare() function. But, more interestingly, if the expressions results in node-sets with at least one
node, and that node is an existing leaf that leafs value is compared with the other expression, and if the other
expression is a constant that expression is converted to an internal value with the same type as the expression
that resulted in a leaf. Thus making it possible to order values based on the internal representation rather than
the string representation. For example, given a leaf:
leaf foo {
type enumeration {
enum ccc;
enum bbb;
enum aaa;
}
}
It would be possible to call compare(foo, 'bbb') (which, for example, would return -1 if foo='ccc'). Or to have
a must expression like this: must "compare(.,'bbb') >= 0"; which would require foo to be set to 'bbb' or 'aaa'.
If one of the expressions result in an empty node-set, a non-leaf node, or if the constant can't be converted to
the other expressions type then NaN is returned.
number min(node-set)
Returns the numerically smallest number in the node-set, or NaN if the node-set is empty.
number max(node-set)
Returns the numerically largest number in the node-set, or NaN if the node-set is empty.
number avg(node-set)
Returns the numerical average of the node-set, or NaN if the node-set is empty, or if any numerical
conversion of a node failed.
number band(number, number)

Returns the result of bitwise AND:ing the two numbers. Unless the numbers are integers NaN will be
returned.
number bor(number, number)

Returns the result of bitwise OR:ing the two numbers. Unless the numbers are integers NaN will be returned.
number bxor(number, number)

Returns the result of bitwise Exclusive OR:ing the two numbers. Unless the numbers are integers NaN will
be returned.
number bnot(number)
Returns the result of bitwise NOT on number. Unless the number is an integer NaN will be returned.
node-set sort-by(node-set, string)
The sort-by() function makes it possible to order a node-set according to a secondary index (see the
tailf:secondary-index extension). The first argument must be an expression that evaluates to a
node-set, where the nodes in the node-set are all list instances of the same list. The second argument must be
the name of an existing secondary index on that list. For example given the YANG model:
container sys {
list host {
key name;
unique number;
tailf:secondary-index number {
tailf:index-leafs "number";
}
leaf name {
type string;
}
leaf number {
type uint32;
mandatory true;
}
leaf enabled {
type boolean;
default true;
}
...
}
}
The expression sort-by(/sys/host,"number") would result in all hosts, sorted by their number. And the
expression, sort-by(/sys/host[enabled='true'],"number") would result in all enabled hosts, sorted by number.
Note also that since the function returns a node-set it is also legal to add location steps to the result. I.e. the
expression sort-by(/sys/host[enabled='true'],"number")/name results in all host names sorted by the hosts
number.

XPath Hints
admin@nso# show running-config devices device PE11 config ios:interface | display xml
<Loopback>
<name>0</name>
<ip>
<address>
<primary>
<mask>255.255.255.255</mask>
</primary>
</address>
</ip>
</Loopback>
<GigabitEthernet>
<name>0/1</name>
<ip>
<address>
<primary>
...
 Use the | display xml option to display part of the configuration in XML format
The figure illustrates how the NSO CLI can be used to retrieve portions of configurations and display them in
XML format to determine the data node hierarchy.
XPath Hints
admin@nso# show running-config devices device PE11 config ios:interface | display xpath
/devices/device[name='PE11']/config/ios:interface/Loopback[name='0']/ip/address/primary/address 10.1.1.17
/devices/device[name='PE11']/config/ios:interface/Loopback[name='0']/ip/address/primary/mask 255.255.255.255
/devices/device[name='PE11']/config/ios:interface/GigabitEthernet[name='0/1']/ip/address/primary/address 10.1.2.1
/devices/device[name='PE11']/config/ios:interface/GigabitEthernet[name='0/1']/ip/address/primary/mask 255.255.255.252
/devices/device[name='PE11']/config/ios:interface/GigabitEthernet[name=’1/1']/ip/address/primary/address 10.1.3.1
/devices/device[name='PE11']/config/ios:interface/GigabitEthernet[name=’1/1']/ip/address/primary/mask 255.255.255.252
...
 Use the | display xpath option to display part of the configuration in XPath format
 Useful when constructing XPath expressions for leafref, must or when statements
The figure illustrates an even better way how the NSO CLI can be used to determine the data node hierarchy.
The | display xpath option can be used to display output using XPath notation that can then be reused to
build XPath expressions.

YANG Examples
This topic provides two examples to illustrate the advantages of YANG.
Examples
 Two examples to illustrate the

Illustrates the versatility of
distinction between:
YANG
 YANG used within NEDs to model device
CLI
 YANG used for service modeling: Illustrates simplicity
 Vendor independent configuration of services (the main focus of this course)
 Simplicity
 Another example to practice
troubleshooting YANG
The two examples will illustrate two scenarios where YANG is used within Cisco NSO:
 To build vendor-specific and device-specific functionality (i.e. Network Element Driver or NED). This
example illustrates the work typically performed by NSO developers where the knowledge of specific
features and technologies is needed in order to build the capability to manage a device using its native
CLI.
This example illustrates the work typically performed by NSO developers where the knowledge of specific
features and technologies is needed in order to build the capability to manage a device using its native CLI.
 To build vendor-independent and device-independent service models (this is the main focus of this
course). You will also note the distinction between the YANG used for NED which carries the
complexities associated with element management and the service models which provide much greater
simplicity.
Example 1: Basic VPLS Configuration
!
! Create a Virtual Forwarding Instance
!
l2 vfi name { autodiscovery | manual }
vpn id id
bridge-domain domain
!
!
! Configure an interface for VPLS
!
interface interface
service instance instance ethernet
encapsulation { untagged | dot1q vlan } PE-X
bridge-domain domain
neighbor neighbor encapsulation mpls
! CE
!
 Vendor-specific example: Cisco IOS

 A subset of possible VPLS configuration options:
 Signaling: auto-discovery or point-to-point VFI
 Encapsulation: untagged or 802.1q
 Switching parameter: VPN identifier, bridge domain
 There is an interdependency between commands which can easily be represented in YANG
The first example illustrates how the NED for Cisco IOS can be augmented to support the implementation of
basic Virtual Private LAN Services (VPLS) with the following service configuration options:
 Signaling: auto discovery using Border Gateway Protocol (BGP) or manual configuration using point-
to-point Virtual Forwarding Interface (VFI).
 Encapsulation: untagged Ethernet frames or 802.1q VLANs.
 Switching parameter: VPN identifier, bridge domain.
The above configuration shows the chosen subset of VPLS configuration options that will be used to enable
the Cisco IOS NED to configure VPLS on Cisco IOS routers.

Example 1: Basic VPLS Configuration (Cont.)
container l2 {
list vfi {
key "name mode";  In NSO, YANG keywords may equal
leaf name { native CLI commands or arguments
type string;
}
leaf mode {
type enumeration {
enum autodiscovery;
}
enum manual; Cisco IOS
} l2 vfi name { autodiscovery | manual }
container vpn { vpn id id
leaf id { bridge-domain domain
type uint32 {
range "1..8000"; !
}
}
}
container bridge-domain {
leaf id {
type uint32 {
range "1..4096";
} Note! The example does not show NSO-specific
}
} annotations that govern the meaning of keywords
} when creating a NED feature.
}
The above example illustrates how YANG data model is mapped to the first part of the VPLS configuration.
The data types and constraints are defined to catch wrong data before it is pushed to a router.
Note This example does not show the specific annotations that are also required for Cisco NSO to properly
transform the YANG statements into Cisco IOS CLI commands.
Example 1: Basic VPLS Configuration (Cont.)
container service {
list instance {
key "id mode";  This top-level container should be
leaf id {
type uint32 { range "1..8000"; } part of the interface configuration
}
leaf mode {
node
type enumeration {
enum ethernet {
}
} interface X/Y
} service instance instance ethernet
container encapsulation { encapsulation { untagged | dot1q vlan }
leaf untagged { type empty; } bridge-domain domain [split-horizon]
container dot1q {
leaf vlan { !
type uint32 { range "1..4096"; }
}
}
}
container bridge-domain {
leaf id {
type uint32 { range "1..4096"; }
}
leaf split-horizon { type empty; }
}
}
}
The second part of the example illustrates the interface-specific part of the VPLS configuration and how it is
mapped form YANG to Cisco IOS CLI.
Note This example does not show the specific annotations that are also required for Cisco NSO to properly
transform the YANG statements into Cisco IOS CLI commands.

Example 2: Basic VPLS Service Configuration
!
! VPLS Service Description
!
vpls service: service-name
device: device1
bridge-domain: domain
interface: interface1
encapsulation: { untagged | dot1q vlan }
interface: interface2
...
device: device2 PE-X
bridge-domain: domain
interface: interface1 CE
...
 Platform-dependent translation handled by NSO

 A selected set of VPLS configuration options has been determined at service design time (e.g.
signaling auto-discovery)
 Service configuration is network-wide
 Only the remaining parameters matter to the operator:
 Encapsulation: untagged or 802.1q VLAN
 Bridge domain
The second example shows how a VPLS service is defined at a higher level where only the service
parameters are important to the operator. The pseudo-language used above describes which parameters are
needed when designing a VPLS service.
Example 2: Basic VPLS Service Configuration (Cont.)
list vpls {
key service-name;
description "Service name";  Only the parameters matter to the
leaf service-name { type string; }
list device {
operator
key device-name;
unique bridge-domain;
 Service is mapped to the actual
leaf device-name { type string; }
leaf bridge-domain {
configuration based on individual
type uint32;
range "1..4096";
device's NED type
}
list interface {
key intf-name;
leaf intf-name { type string; }
leaf encapsulation {
type union{
type uint32 {
range "1..4096";
}
type enumeration {
enum "Untagged";
}
}
} Note! The example does not show the mapping
}
} template.
}
The sample YANG service model illustrates how the service can be defined and it is independent of the
specifics of individual device types – devices can be of different types and from different vendors as long as
they support the required set of features to enable VPLS.
Note Note! The above example does not show the mapping of the service model to the individual device types.

Example 3: Spot the Error
Module file: lpbck.yang
module Loopback {
namespace "http://com/example/Loopback";
prefix Loopback;
import ietf-inet-types;
 Syntax errors?
list Loopback{
key servicename
 Semantic errors?
unique servicename;
leaf servicename {
description "Service Instance Name";  Warnings?
type string;
}
leaf device {
description "Loopback interface number";
type string {
pattern '[a-zA-Z][a-zA-Z0-9-_*';
}
}
key Loopback;
unique ip-address;
leaf Loopback {
description "Loopback interface number";
type string {
range "0-999";
}
}
}
leaf ip-address { type inet:ipv4-address; }
}
}
The last example is intended to practice the YANG syntax and semantics skills by first trying to find errors in
existing YANG modules before starting to write one's own YANG modules.
Try to find errors in the above example:
 Syntax errors may stop the YANG module from being parsed properly.
 Semantic errors may prevent YANG from interpreting the data model properly.
 Non-fatal mistakes may produce warnings (e.g. redundancy, sub-optimal code).
Use pyang to Validate the Code
root@NCS:/tmp# pyang lpbck.yang
lpbck.yang:9: error: unterminated statement definition for keyword "key", looking at u Missing ";"
root@NCS:/tmp#
root@NCS:/tmp# vim lpbck.yang Fix syntax errors.
root@NCS:/tmp#
root@NCS:/tmp# pyang lpbck.yang
lpbck.yang:1: warning: unexpected modulename "loopback" in lpbck.yang, should be lpbck
lpbck.yang:4: error: expected keyword "prefix" as child to "import"
lpbck.yang:5: warning: imported module ietf-yang-types not used
lpbck.yang:9: warning: all keys in the list are redundantly present in the unique statement
lpbck.yang:17: error: syntax error in pattern: xmlRegexpCompile() failed
lpbck.yang:22: error: the identifier "ip-address" in the unique argument does not reference an existing
container
lpbck.yang:26: error: bad value "0-999" (should be range-arg)
lpbck.yang:26: error: restriction range not allowed for this base type
lpbck.yang:30: error: prefix "inet" is not defined (reported only once)
root@NCS:/tmp#
root@NCS:/tmp# mv lpbck.yang loopback.yang
root@NCS:/tmp#
root@NCS:/tmp# vim loopback.yang Fix remaining syntax and semantic errors.
root@NCS:/tmp#
root@NCS:/tmp# pyang loopback.yang No news is good news.
 Preferably use an IDE for YANG which has syntax highlighting and YANG validation
capability (e.g. Eclipse)
Missing semicolons or curly brackets prevent the YANG parser to read the file properly so it will not report
all errors but instead you will have to find and fix them one by one. This may require many iterations with
pyang before you can start troubleshooting other syntactic and semantic errors.
Once the YANG module can be parsed, the pyang tool will search for other types of syntax errors and
semantic errors. The above output should give you enough information to fix the errors in your YANG
module.
Once you have foxed all mistakes, the pyang tool should not produce any output which means that there is
nothing wrong with the syntax and semantics of the module.

Example 3: Spot the Error
Module file: lpbck.yang  Loopback.yang
module loopback {
namespace "http://com/example/Loopback"; Syntax errors:
prefix loopback;
import ietf-inet-types;{ prefix inet; }  Missing ";"
 Missing "]" in pattern
list loopback{
key servicename ;  Wrong range character; use ".." instead of "-"
unique servicename;
leaf servicename {  Wrong Loopback leaf type; use uint16 instead of
description "Service Instance Name";
type string; string
}
leaf device {  Character range not closed by "]" in the regex
description "Device Hostname";
type string { pattern
pattern '[a-zA-Z][a-zA-Z0-9-_ ]
]*';
}
}
Semantic errors:
key loopback;
unique ip-address;  ip-address leaf should be within the loopback-
leaf loopback { interface list where it is also required to be
description "Loopback interface number"
type uint16
string { unique
.. 999";
range "0..
}
}
leaf ip-address { type inet:ipv4-address; }
Warnings:
}
leaf ip-address { type inet:ipv4-address; }  Module ietf-yang-types is not used
}
}  Unique statement is not required because key
also enforces uniqueness for leaf "servicename"
The above illustration shows the solution to the quest to find errors.
Summary
 IETF RFCs:
 YANG: http://tools.ietf.org/html/rfc6020
 Common YANG Data Types: http://tools.ietf.org/html/rfc6991
 Guidelines for Authors of YANG: http://tools.ietf.org/html/rfc6087
 An Architecture Using NETCONF and YANG: http://tools.ietf.org/html/rfc6244
 Pyang tool:
 Validation: pyang test.yang
 Conversion: pyang -f yin test.yang
 Text representation: pyang -f tree test.yang
 HTML representation: pyang -f jstree test.yang
 Use an IDE with yang syntax highlighting and YANG validation capabilities to simplify
development (e.g. Eclipse)
References
 Cisco NSO documentation and manuals.
 IETF RFC 6020
 W3C XPath 1.0 specification

Lesson 2-1
System Setup
Overview
This lesson describes the steps required to install and prepare the environment for your first
project.
Objectives
 Describe the NSO installation procedure
 Explain how the integrated network simulation tool can be used to quickly test NSO
functionalities against simulated devices
 Describe how the integrated discovery module can be used to make an initial import of
devices to NSO
 Describe how packages are imported into NSO
Cisco NSO Setup Overview
This topic will provide an overview of Cisco Network Services Orchestrator system setup
requirements and procedures.
System Requirements: Operating System
 Supported architecture: 64-bit x86 architecture

 Two distributions available:
 OSX (e.g. nso-4.1.1.darwin.x86_64.installer.bin)
 Linux (e.g. nso-4.1.1.linux.x86_64.installer.bin)
 Java JDK version 6.0 or higher (i.e. development version
1.6 or higher)
Before installing NSO, you need to know your system specifications (Operating System and CPU
architecture) to choose the appropriate NCS Installer. NSO is delivered as a self-extract archive which is
OS/CPU specific. The archive file has the pattern ncs-VERSION.OS.ARCH.installer.bin. The variables in
the pattern refer to:
 VERSION: The version to install.
 OS: The Operating System (linux for all Linux distributions and darwin for OS X).
 ARCH: The CPU architecture (x86_64 or i686).
Before installing, ensure that a Java JDK-6.0 or higher is installed. When JDK is properly installed the
command java -version should indicate a Java version of "1.6" or higher.
System Requirements: Memory and CPU
 Depends on complexity: Number of services, number of devices, service complexity
 Example: NSO running on quad-core CPU and 32 GB RAM
RAM Memory for 10 000 Services Database disc space for 10 000 Services
NSO is a highly scalable system but if you are looking for templates for NSO server sizing you will not find
any. The NSO server system requirements vary between deployments and are based on the number of
services running in the network, the number of managed devices and actual service complexity. Having a
simple firewall service will consume less resources than a more complex service like triple play.
To illustrate the capabilities of NSO, some performance graphs are provided as an example.
© 2016 Cisco Systems, Inc. Start Using Cisco NSO 2-3

Cisco NSO Typical Environment Requirements
 Production
 One, two or many Cisco NSO production systems
 High availability and clustering used if/when required
 Pre-Production Verification Lab

 Replicated production environment in a lab for development and testing purposes
 A subset of managed physical devices in the lab
 Optionally, a comparable set of virtual devices
 Augmented by many simulated instances of Netsim devices
 Development and Testing Lab and Desktop Development

 Desktop instances for development and testing
 Many simulated instances of Netsim devices
An environment making use of Cisco NSO to orchestrate end-to-end services may require the following
different deployment of Cisco NSO:
 Production: this is the critical running production environment which should be used solely for the
purpose of orchestrating production services.
 Pre-Production Verification Lab: this environment should be a replicated production environment in a
lab for development and testing purposes with a subset of managed physical devices in the lab to cover
each device type and each use case. Optionally, a comparable set of virtual devices can be used to limit
the cost of the lab and improve the flexibility of the lab. Additionally, the lab can be augmented by
many simulated instances using Netsim devices.
 Development and Testing Lab and Desktop Development: this environment is a non-critical
environment used to design and test various use cases, to develop new production services or update
existing services, etc. This environment will typically use Netsim devices or virtual devices for
development and testing purposes.
Cisco NSO Cisco NSO
System Installation Local Installation
 Intended for production environment and  Intended for development and testing in
pre-production verification lab labs and on desktops
 NSO can run as root or specific user  NSO can run as user
(from version 4.0.1)
 Simple to switch between NSO instances
 System integrated with the Linux OS: (versions)
 Installation directory: /op/ncs/ncs-4.1.1  Everything installed in one or two
(linked to by /opt/ncs/current)
directories
 Running directory: /var/opt/ncs
 Installation directory: all static files (e.g.
 Log directory: /var/log/ncs binaries, libraries, scripts, tools)
 Configuration directory: /etc/ncs  Running directory: all dynamic files (e.g.
CDB, logs, configuration, packages)
Local Install
Use Local Install --local-install option for Development, Evaluation, proof of concept and private lab
purposes. All the NSO Examples and README steps provided with the installation are based on Local
Install only. You should always use Local Install for evaluation and development purposes. Local Install is
possible on Linux OS and OS X.
System Install
Use System Install --system-install option for production and system-wide deployment in a central location.
You need root priviliges for System Install procedure and administration of the installed NSO. As part of
System install, the NSO daemon ncs is started at boot time. System Install should be used only for
production deployment. For all other purposes, use Local Install procedure.

Cisco NSO Local Installation
This topic will guide you through Cisco Network Services Orchestrator installation procedure
using the local installation option for development and testing purposes.
Cisco NSO Local Installation Procedure
1. System requirements check Duration: ~ 1 min
2. Install NSO
3. Create running environment for NSO
4. Start NSO
The NSO installation only requires a handful of steps and can be completed in minutes.
 NSO installation file contents: Installation directory in
the current directory
 NSO software, examples, documentation
(user home directory in
 Lab-grade network element drivers (NEDs)
the example)
 Netsim network simulator
 Run the installation:

cisco@nso:~$ sh nso-4.1.1.linux.x86_64.installer.bin ncs-4.1.1
INFO Using temporary directory /tmp/ncs_installer.29161 to stage NCS installation bundle
INFO Unpacked ncs-4.1.1 in /home/cisco/ncs-4.1.1
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/cisco/ncs-4.1.1/ncsrc
INFO NCS installation script finished
INFO Found and unpacked corresponding NETSIM_PACKAGE
INFO NCS installation complete
cisco@nso:~$
Installing Cisco NSO can be done in seconds. You need the self-extract archive suitable for your OS and
CPU, and all you need to decide is where Cisco NSO should be installed. For training purposes, you could
very well install Cisco NSO in your home directory, e.g. as ~/Cisco ncs/3.0.

Directory Structure
You may have multiple installation
~ ncs-4.0.1/
directories for multiple version of NSO
ncs-4.1/
ncs-4.1.1/ bin/
lib/ Standalone NSO deployments with
Installation
doc/ sample solutions
Directory
examples.ncs web-server/ ncs-cdb/
ncs.conf
datacenter/ ncs-cdb/
ncs-run/ ncs-cdb/
ncs.conf
Running Directory ncs.conf
When working with NSO, one should be aware of two different directory types. The first is the installation
directory itself, which contains all of the NSO components. Note that it is a good practice to run NSO
projects outside the actual installation directory. This will avoid future problems when upgrading NSO to a
newer version and it will clearly separate the NSO installation form its production or project specific settings.
Creating Running Environment
cisco@nso:~$ cd ncs-4.1.1  Make sure binaries are added to your PATH
cisco@nso:~/ncs-4.1.1$ source ncsrc
cisco@nso:~/ncs-4.1.1$ ls -l by sourcing the environment variables
drwxr-xr-x 2 cisco cisco 4096 Jan 23 13:06 bin
-rw-r--r-- 1 cisco cisco 100882 Jan 23 13:06 CHANGES
 The “source ncsrc” is required every time
drwxr-xr-x 5 cisco cisco
4096 Jan 22 21:24 doc
4096 Jan 23 13:04 erlang
you start a shell session
4096 Jan 23 13:01 etc
4096 Jan 23 13:11 examples.ncs
 Alternatively, you may add the “source
drwxr-xr-x 2 cisco cisco 4096 Jan 23 13:04 include ncsrc” command to your .profile or .bashrc
drwxr-xr-x 3 cisco cisco 4096 Jan 23 13:01 java
drwxr-xr-x 7 cisco cisco 4096 Jan 23 13:07 lib file in the home directory
-rw-r--r-- 1 cisco cisco 94796 Jan 23 13:06 LICENSE
drwxr-xr-x 6 cisco cisco 4096 Jan 22 21:05 man
-rw-rw-r-- 1 cisco cisco 546 Feb 18 12:22 ncsrc
-rw-rw-r-- 1 cisco cisco 514 Feb 18 12:22 ncsrc.tcsh
drwxrwxr-x 3 cisco cisco 4096 Feb 18 12:22 netsim
drwxr-xr-x 5 cisco cisco 4096 Jan 23 13:01 packages
-rw-r--r-- 1 cisco cisco 6455 Jan 23 13:06 README
drwxr-xr-x 4 cisco cisco 4096 Jan 23 13:05 scripts
drwxr-xr-x 3 cisco cisco 4096 Jan 23 13:01 src
drwxr-xr-x 4 cisco cisco 4096 Jan 23 13:06 support
drwxr-xr-x 3 cisco cisco 4096 Jan 23 13:01 var
-rw-r--r-- 1 cisco cisco 225 Jan 23 13:06 VERSION
Make sure you have sourced the ncsrc file in $ NCS_DIR. This sets up paths and environment variables in
order to run NSO. So this must be done all times before running NSO, so it is recommended to put that in
your profile.
In the below, replace the name of the binary and directory to install in:
 sh ./ncs-3.0.linux.x86_64.installer.bin ~/ncs/3.0
 source ~/ncs/3.0/ncsrc
The “source” line ensures the Cisco NSO executable and associated tools will be in your PATH. With this,
you can refer to the location where Cisco NSO is installed as $ Cisco NCS_DIR. If you like, you could put
that source command into your .bashrc, so that Cisco NSO will be in your path every time you log in.
Create an empty directory, for example in your home directory. NSO and the simulator will create files and
directories in this example directory. Make sure you change to this directory before continuing.

Creating Running Environment
cisco@nso:~$ ncs-setup --dest ncs-run Run the ncs-setup script to creates
cisco@nso:~$ cd ncs-run
cisco@nso:~/ncs-run$ ls –l a directory for the running
drwxrwxr-x 2 cisco cisco 4096 Feb 18 12:31 logs environment containing a number of
drwxrwxr-x 2 cisco cisco 4096 Feb 18 12:31 ncs-cdb subdirectories and files:
-rw-rw-r-- 1 cisco cisco 8234 Feb 18 12:31 ncs.conf
drwxrwxr-x 2 cisco cisco 4096 Feb 18 12:31 packages  database directory ncs-cdb
-rw-rw-r-- 1 cisco cisco 604 Feb 18 12:31 README.ncs
drwxrwxr-x 4 cisco cisco 4096 Feb 18 12:31 scripts  log directory log
drwxrwxr-x 3 cisco cisco 4096 Feb 18 12:31 state  empty packages directory
 default ncs.conf
NSO runs as a daemon, and needs a couple of directories (for logs, its database etc.). The location of all these
are in a configuration file, usually called ncs.conf. Unless supplied as an argument (using the –c option) the
NSO daemon will look for ./ncs.conf, followed by etc/ncs/ncs.conf in the NSO installation directory. In order
to make it easy to get started NSO includes a script called ncs-setup, this script will create the directories and
files needed to get started (by default in the current working directory).
Starting Cisco NSO
 Start the NSO daemon:
cisco@nso:~$ ncs
 Check if the deamon is running:

cisco@nso:~$ ncs --status
 Access the CLI (Cisco XR style):

cisco@nso:~$ ncs ncs_cli –C –u admin
 Start the CLI (Juniper style):

cisco@nso:~$ ncs ncs_cli –J –u admin
An initial configuration file, ./ncs.conf and the directories need to run NSO were created. Now, to start the
NSO daemon run "ncs" (optionally providing the configuration file as argument: -c ./ncs.conf):
 ncs
The NSO daemon is now running, we can make sure it is by issuing:
 ncs –status
The next thing to do is to start the CLI. The CLI is started using the ncs_cli command. By default you start
the CLI as the user you are running the shell as. Most examples will use a default built-in user called 'admin',
to start the CLI as user admin, use:
 ncs_cli -u admin
The NSO CLI provides a unified CLI towards the complete network. It comes in two flavors Juniper-style
and Cisco XR style. Note that the NSO CLI is a northbound interface to the NSO representation of the
network devices and network services; do not confuse this with a cut-through CLI that reaches the devices
directly. So although the network might be a mix of vendors and device interfaces like different CLI flavors,
NSO provides one northbound CLI.

Remote Access to NSO
 You can access the NSO CLI using  You can access the WebUI
SSH: using a browser:
cisco@nso:~$ ssh -l admin -p 2024 localhost
admin@localhost's password:
By default NSO also starts its built-in Secure Shell (SSH) server, listening on port 2024. So SSH can also be
used to log into the CLI using the ssh -l admin -p 2024 localhost command.
The default password for the 'admin' user is: admin. Type exit to get out of the CLI.
admin connected from 127.0.0.1 using ssh on host.example.org

admin@host> exit
Connection to localhost closed.
NSO also starts a web-server, listening on port 8080. By directing a browser to http://localhost:8080/ you can
login using the web browser user interface (WebUI) with user admin again.
Other Commands
 Stop the NSO daemon:
cisco@nso:~$ ncs --stop
 Inspect system logs:

cisco@nso:~$ more ncs-run/logs/ncs.log
 Restore system defaults and clear logs:

cisco@nso:~/ncs-run$ ncs-setup --reset
Stop the NSO daemon use the --stop option:

 ncs –stop
NSO will now have lots of logs in the logs directory. The main log being logs/ncs.log, look at the log to see
when it was started, what files were loaded during start etc.
 less logs/ncs.log
To wipe all log-files, restore all settings done in NSO, and to revert to the "empty" factory default
configuration, use the --reset option to ncs-setup:
 ncs-setup --reset

Cisco NSO System Installation
This topic will guide you through Cisco Network Services Orchestrator installation procedure
using the system installation option for production purposes.
Cisco NSO Installation Procedure
1. System requirements check Duration: ~ 1 min
2. Install NSO
3. Start NSO
NSO System Install results in system wide Installation and Deployment. Use this Install option only for
Production deployment. For Development and Evaluation purposes, you should use only Local Install
procedure.
Before installing NSO:
1. Ensure that the root permissions are enabled.
2. Choose the correct Operating System (Linux). Currently only Linux OS is supported.
3. Ensure that Java JDK-6.0 or higher is installed.
Uses default directories
Cisco NSO System Installation unless otherwise
specified in parameters
cisco@nso:~$ sudo sh nso-4.1.1.linux.x86_64.installer.bin --system-install
INFO Using temporary directory /tmp/ncs_installer.27219 to stage NCS installation bundle
INFO Using /opt/ncs/ncs-4.1.1/ncs-4.1.1 for static files
INFO Using /etc/ncs for configuration files
INFO Using /var/opt/ncs for run-time state files
INFO Using /var/log/ncs for log files
INFO Unpacked ncs-4.1.1 in /opt/ncs/ncs-4.1.1/ncs-4.1.1
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 /opt/ncs/ncs-4.1.1/ncs-4.1.1/ncsrc
INFO NCS installation script finished
INFO Found and unpacked corresponding NETSIM_PACKAGE
INFO Configuring installation for PAM authentication
INFO Using PAM service common-auth for authentication
INFO Generating self-signed certificates for HTTPS
...
Installing Cisco NSO can be done in seconds. You need the self-extract archive suitable for your OS and
CPU, and all you need to decide is where Cisco NSO should be installed. For training purposes, you could
very well install Cisco NSO in your home directory, e.g. as ~/Cisco ncs/3.0.
Use --system-install option to perform a system installation. This option creates a system install of NSO,
suitable for deployment.
sudo sh nso-VERSION.OS.ARCH.installer.bin --system-install
The variables in the command VERSION refers to the NSO version to install. OS refers to the Operating
System (linux). ARCH refers to the CPU architecture (x86_64 or i686).For example:
sudo sh nso-4.1.1.linux.x86_64.installer.bin --system-install

Cisco NSO System Installation (Cont.)
...
INFO Installed user profile script ncs.csh in /etc/profile.d
INFO Installed 'logrotate' configuration file ncs in /etc/logrotate.d
INFO The installation has been configured for PAM authentication,
INFO with group assignment based on the OS group database
INFO (e.g. /etc/group file). Users that need access to NCS must
INFO belong to either the 'ncsadmin' group (for unlimited access
Uses different defaults
INFO rights) or the 'ncsoper' group (for minimal access rights). than Local Installation
INFO To create the 'ncsadmin' group, use OS shell command:
groupadd ncsadmin
INFO To create the 'ncsoper' group, use OS shell command:
groupadd ncsoper
INFO To add an existing user to one of these groups, use OS shell command:
usermod -a -G <groupname> <username>
INFO NCS installation complete
cisco@nso:~$
The continuation of the output from system installation shows that PAM is used for authenticating NSO
users and provides some guidelines how to create groups and add users to groups.
Directory Structure
/ opt/ ncs/ ncs-4.0.1/
ncs-4.1/
ncs-4.1.1/ bin/
lib/
Symbolic link Installation Directory
doc/
current/ examples.ncs
var/ opt/ ncs/ ncs-cdb/ Running Directory
etc/ ncs/ ncs.conf Configuration Directory
By default, when using system installation, the Installation Directory is created in /opt/ncs, the Configuration
Directory is created in /etc/ncs, the Running Directory is created in /var/opt/ncs and the Log Directory is
created in /var/log/ncs.

Starting Cisco NSO
cisco@nso:~$ sudo /etc/init.d ncs
Usage: ncs {start|stop|restart|reload|status}  Use init.d script ncs
cisco@nso:~$ sudo /etc/init.d ncs start
Starting ncs: .
 Start the NSO daemon
cisco@nso:~$ sudo /etc/init.d ncs status  Verify the NSO system status:
vsn: 4.1.1
SMP support: no
sudo /etc/init.d ncs status
Using epoll: yes or
available modules:
backplane,netconf,cdb,cli,snmp,webui ncs --status
running modules:
backplane,netconf,cdb,cli,webui
status: started
...
Use the init.d script ncs to control the status of the NSO daemon.
Installing NEDs
This topic describes how NED packages are loaded into a new NSO project.
Network Element Driver Overview
 NEDs are distributed as compressed TAR files (.tar.gz)

 NEDs are NSO packages
 NSO expects to find packages in the packages subdirectory of the
running directory:
 Don’t store anything else in the packages directory!
 Don’t keep “old” packages in the packages directory!
 Packages made for different versions of NSO may need to be

recompiled
All user code that needs to run in NSO must be part of a package. A package is basically a directory of files
with a fixed file structure. A package consists of code, YANG modules, custom Web UI widgets
etc., that are needed in order to add an application or function to NSO. Packages is a controlled way to
manage loading and versions of custom applications.
When NSO starts, it needs to search for packages to load. The ncs.conf parameter /ncs-config/ load-path
defines a list of directories. At initial startup, NSO searches these directories for packages, copies the
packages to a private directory tree in the directory defined by the /ncs-config/ state-dir parameter in
ncs.conf, and loads and starts all the packages found. All .fxs (compiled YANG files) and .ccl (compiled CLI
spec files) files found in the directory load-dir in a package are loaded.

Installing NEDs
System Installation Local Installation
 Extract the package to /var/opt/packages  Extract the package to the /packages
unless you used a non-default location subdirectory of the running directory
 Alternatively, link to the lab-grade packages
in the installation directory
cisco@nso:/var/opt/ncs/packages$ sudo sudo tar -xzvf /tmp/ncs-4.1.1-cisco-ios-4.0.4.tar.gz cisco-ios

cisco-ios/
cisco-ios/build-meta-data.xml
cisco-ios/CHANGES
cisco-ios/README
cisco-ios/netsim/
...
cisco@nso:/var/opt/ncs/packages$ sudo tar -xzvf /tmp/ncs-4.1.1-cisco-iosxr-4.1.tar.gz cisco-iosxr
cisco-iosxr/
cisco-iosxr/build-meta-data.xml
cisco-iosxr/CHANGES
cisco-iosxr/netsim/
...
There are many ways how you can choose to manage package repositories. Whatever choice you select you
must ensure that package directories (and only package directories) are visible and accessible in the NSO’s
packages subdirectory of the running directors:
 Extract tar.gz files to the packages directory
 Copy existing package directories to the packages directory (shown on next page)
 Link to existing package directories from the packages directory (shown on next page)
Using Existing Packages
 Existing packages:
 NEDS ($NCS_DIR/packages/neds)
 Services ($NCS_DIR/packages/services)
 Tools ($NCS_DIR/packages/tools)
 Copy or softlink packages from the NSO installation or another location where
the packages are stored:
cisco@nso:/var/opt/ncs/packages$ sudo cp -r $NCS_DIR/packages/neds/cisco-ios packages/
cisco@nso:/var/opt/ncs/packages$ sudo cp -r $NCS_DIR/packages/neds/cisco-iosxr packages/
or
cisco@nso:/var/opt/ncs/packages$ sudo ln -s $NCS_DIR/packages/neds/cisco-iosxr packages/cisco-ios
cisco@nso:/var/opt/ncs/packages$ sudo ln -s $NCS_DIR/packages/neds/cisco-iosxr packages/cisco-iosxr
Existing packages can be found in the NSO installation directory ($NCS_DIR) under a folder called
packages. The existing packages are split into three groups:
 NEDs: contains network element drivers for network devices.
 Services: contains services like L3 VPNs, openstack etc.
 Tools: contains services that can be used with NSO like Discovery Module.
To reuse the existing packages in production environments, the existing packages need to be copied to the
package folder in the project directory. A softlink can also be used as an alternative to copying the package
folder.

Activate NED Packages
 Any change in the package will not be automatically activate:

 Recompile packages (optional; used when package was compiled using a
different version of NSO)
 Reload packages to activate them
 Verify packages
To ensure proper behavior of packages it is recommended to:

 re-compile packages using the make command in the src subdirectory of the packages directory.
 reload packages in NSO CLI
 verify packages
Compile Packages
root@nso:/var/opt/ncs/packages# cd cisco-ios/src
root@nso:/var/opt/ncs/packages/cisco-ios/src# make
cd java && ant -q all
BUILD SUCCESSFUL
Total time: 0 seconds
cd ../netsim && make all
make[1]: Entering directory `/var/opt/ncs/packages/cisco-ios/netsim'
make[1]: Nothing to be done for `all'.
make[1]: Leaving directory `/var/opt/ncs/packages/cisco-ios/netsim‘
root@nso:/var/opt/ncs/packages/cisco-ios/src#
 Compile packages to ensure they are compiled by the correct version of the
compiler
 You may also do make clean and then make to perform a complete recompile
of the package
The figure illustrates the compilation procedure for a NED package for Cisco IOS routers management.
Make sure that the compilation reports “BUILD SUCCESSFUL”. If the compilation fails, the file and line
number of failed source will be displayed.

Reload Packages
admin@ncs# packages reload
>>> System upgrade is starting.
>>> Sessions in configure mode must exit to operational mode.
>>> No configuration changes can be performed until upgrade has completed.
reload-result {
package cisco-ios
result true
}
reload-result {
package cisco-iosxr
result true
}
admin@ncs#
 Depending on the number of packages it may take some time for the package
upgrade process to complete
 It may take even longer in case a package upgrade is performed in a live
system with multiple service packages with many service instances
The figure illustrates the usage of the packages reload command when using the Cisco style CLI. If using
the Juniper style CLI use the request packages reload command.
This request makes NSO copy all packages found in the load path to a temporary version of its private
directory (packages-in-use.new), and load the packages from this directory. If the loading is successful, this
temporary directory will be made permanent, otherwise the temporary directory is removed and NSO
continues to use the previous version of the packages. Thus when updating packages, one should always
update the version in the load path, and request that NSO does the reload via this action.
In some cases we may want NSO to do the same operation as the reload action at NSO startup, i.e. copy all
packages from the load path before loading, even though the private directory copy already exists. This can
be achieved in two different ways:
 Setting the shell environment variable $NCS_RELOAD_PACKAGES to true. This will make NSO do
the copy from the load path on every startup, as long as the environment variable is set, and may be
useful in some development scenarios.
 Giving the option --with-package-reload to the ncs command when starting NSO. This will make NSO
do the copy from the load path on this particular startup, without affecting the behavior on subsequent
startups. This should always be used when upgrading to a new version of NSO in an existing directory
structure, to make sure that new packages are loaded together with the other parts of the new system.
Verifying Packages
admin@ncs# show packages package package-version
PACKAGE
NAME VERSION
----------------------
cisco-ios 4.0.4
cisco-iosxr 4.1
admin@ncs#
 Check if all the required packages are loaded using the show packages
command
The purpose of this procedure is to make it possible to reliably do a package reload while NSO is running,
with fallback to the previously existing version of the packages if the reload should fail. Such a reload can be
requested via the reload action - from the NSO CLI.

Other NSO System Process Maintenance Options
 After changing the configuration (ncs.conf) it is enough to reload the
configuration: System installation Local installation
cisco@ncs:~$ ncs --reload cisco@ncs:~$ ncs --reload
or
cisco@ncs:~$ sudo /etc/init.d/ncs reload
 Restarting NSO: System installation Local installation

cisco@ncs:~# sudo /etc/init.d/ncs restart cisco@ncs:~$ ncs --stop
cisco@ncs:~$ ncs
 Restarting NSO and reloading:

System installation Local installation
cisco@ncs:~$ sudo NCS_RELOAD_PACKAGES=true /etc/init.d/ncs restart cisco@ncs:~$ ncs --stop
cisco@ncs:~$ ncs --with-package-reload
The figure illustrates the various options available to re-initialize the NSO system:
 After changing the ncs.conf file it is enough to trigger a reload using the ncs --reload command.
 When a complete restart is required you should use the /etc/init.d/ncs restart command if you are using
the system installation or use the ncs --stop command to stop the server and ncs to start the server. Note
that a server restart does not initiate a package reload action. You should use the packages reload CLI
command or use the --with-packkage-reload flag when starting a locally-installed NSO.
Using Netsim
This topic describes how the integrated Netsim tool can be used to simulate network devices.
Netsim Overview
 ncs-netsim is a network devices

simulation tool
 Used to test NSO with simulated
devices
 Uses NED device packages Netsim simulated
 A NED package contains netsim devices (ConfD)
directory
 Represents device configuration and
CLI
 The same YANG models are used Physical or virtual non-
for simulated and real devices simulated devices
The ncs-netsim program is a useful tool to simulate a network of devices to be managed by NSO. It makes it
easy to test NSO packages towards simulated devices. All you need is the NSO Network Element Driver
(NED) packages for the devices that you need to simulate. The devices are simulated with the Tail-f ConfD
product. All the NSO examples use ncs-netsim to simulate the devices. A good way to learn how to use ncs-
netsim is to study these.
Netsim enables you to test the device configuration before it is deployed to real devices. NSO uses the same
YANG model for both the real and Netsim simulated devices. Netsim capabilities of a NED package are
defined in its netsim subfolder and are beyond the scope of this course.

Starting Simulated Devices
 Below example creates 3 Cisco IOS devices: Create 3
devices
cisco@ncs:~$ ncs-netsim create-network <NED package> <#N devices>
cisco@ncs:~$ ncs-netsim create-network $NCS_DIR/packages/neds/cisco-ios 3 c
 Simply run netsim inside the project folder Use prefix

cisco@ncs:~$ ncs-netsim start “c”
DEVICE c0 OK STARTED
cisco@ncs:~$
Start the simulator using the ncs-netsim start command. You should see the devices getting started as shown
above.
Netsim Options
 Netsim supports creating, adding and deleting simulated devices on the fly
cisco@ncs:~$ ncs-netsim --help
Usage ncs-netsim [--dir <NetsimDir>]
create-network <NcsPackageDir> <NumDevices> <Prefix> |

add-to-network <NcsPackageDir> <NumDevices> <Prefix> |
delete-network |
[-a | --async] start [devname] |
[-a | --async ] stop [devname] |
[-a | --async ] reset [devname] |
[-a | --async ] restart [devname] |
list |
is-alive [devname] |
status [devname] |
whichdir |
ncs-xml-init [devname] |
packages |
netconf-console devname [XpathFilter] |
[-w | --window] [cli | cli-c | cli-i] devname
A large simulated network environment can be created if using Netsim-enabled NED packages. Use the
highlighted options to create network and add various types of device to the simulated network.

Access Simulated Devices
 You can run the CLI towards the simulated devices
cisco@ncs:~$ ncs-netsim cli-i c1
admin connected from 127.0.0.1 using console *
c1> enable
c1# show running-config
class-map m
match mpls experimental topmost 1
match packet length max 255
match packet length min 2
match qos-group 1
!
c1# exit
Run the CLI towards one of the devices as shown above. This output shows that the device has some initial
config.
Note Netsim only simulates the CLI. There is no data plane to process packets.
Development Lab Setup Overview
 Setup an NSO running environment:  Start NSO:
 ncs-setup  ncs
 ncs.conf  /etc/init.d/ncs start
 Populate with packages:  ncs --status
 Extract/copy/link the required  Log in:
packages into the packages directory  ssh admin@localhost -p 2024
 Make and start NETSIM devices:  ncs_cli -C -u admin
 Only if you want to use simulated  http://localhost:8080
devices
 ncs-netsim
Use a local installation of NSO together with Netsim to build a learning and development NSO environment.

Summary
 Cisco NSO installation is very easy and can be completed in a matter of minutes.
 Every Cisco NSO deployment should separate the installation folders from project folders
to protect the installation files.
 Cisco NSO provides a network simulation tool called netsim which can simulate device
CLI.
 Cisco NSO provides an optional discovery package to discover network devices.
References
Lesson 2-2
Device Manager
Overview
This lesson introduces the Device Manager component of Cisco Network Services
Orchestrator.
Objectives
Upon completing this lesson, you will be able to:
 Describe how the Device Manager configures network devices
 Explain how Device Manager obtains and maintain connections to network devices
 Describe how the concept of templates and groups can be used in device configuration and
management
 Describe the purpose of tags, annotations, policies and commit queues
 Describe other tools used in device management
 Explain how the WebUI can be used for device management
Overview
This topic introduces the Device Manager and its role in Cisco NSO.
Device Manager
 Its the heart of NSO
 NSO keeps master copy of configuration in CDB
 The job of the Device Manager is to break any network configuration change to
configuration change on managed devices
 Device Manager supports different protocols: Master Configuration
Cisco
 NETCONF
NSO Database
 CLI
 SNMP Network Element Drivers
 Java code
The Device Manager lies at the heart of NSO. The Device Manager maintains a flat list of all managed
devices. NSO keeps the master copy of the configuration for each managed device. Whenever a
configuration change is done to the list of device configuration master copies, the job of the Device Manager
is to partition this "network configuration change" into the corresponding changes for the actual managed
devices. Depending on the device type, different protocols are spoken southbound:
 If the device is a Network Configuration Protocol (NETCONF) capable device, we produce explicit
NETCONF edit-configuration Remote Procedure Call (RPC) operations for each participating device
and then inside the same transaction that runs in the NSO, execute all the individual - device specific -
NETCONF operations.
 If the device is a Simple Network Management Protocol (SNMP) device, NSO translates the change of
the NSO Document Object Model (DOM) tree into the corresponding SNMP (SET command) protocol
data units (PDUs).
 If the device has a CLI which has the same structure as Cisco IOS or XR routers, a CLI NED is used to
produce the correct sequence of CLI commands.
 And finally, for devices that do not fall into any of the above mentioned categories, Java code in a
Generic NED gets invoked with the proposed changes. The job for that Network Element Driver (NED)
code is to translate between the diff on the NSO DOM tree to the corresponding operations on the
device.
The architecture of the NETCONF protocol is the enabling technology here making it possible to push out
configuration changes to managed devices and then in the case of other errors, roll back changes. Devices
that do not speak NETCONF, i.e. devices that do not have transactional capabilities can also participate,
however depending on the device; error recovery may not be as good as it is for a proper NETCONF enabled
device. In order to understand the main idea behind the NSO Device Manager it is necessary to understand
the NSO data model and how NSO incorporates the YANG data models from the different managed devices.
NSO CLI
 In Operational mode, the CLI displays operational data stored in CDB
 In Configuration mode, the CLI displays network configuration data stored in CDB
Cisco Style Juniper Style
admin@nso# operational mode CLI admin@nso> operational mode CLI
admin@nso(config)# configuration mode admin@nso% configuration mode
Operational Mode Configuration Mode

admin@nso# show devices list admin@nso# configure
NAME ADDRESS NED ID ADMIN STATE admin@nso(config)# show full-configuration
------------------------------------------ devices device ce0
P11 127.0.0.1 cisco-ios-xr unlocked
P12 127.0.0.1 cisco-ios-xr unlocked devices device PE11
P21 127.0.0.1 cisco-ios-xr unlocked address 127.0.0.1
PE11 127.0.0.1 cisco-ios unlocked port 10101
PE12 127.0.0.1 cisco-ios unlocked ssh host-key ssh-dss
PE21 127.0.0.1 cisco-ios-xr unlocked key-data ...
PE22 127.0.0.1 cisco-ios-xr unlocked !
... ...
Like many CLIs there is an operational mode and a configuration mode. Operational mode is the initial mode
after successful login to the CLI. It is primarily used for viewing.
The system status, controlling the CLI environment, monitoring and troubleshooting network connectivity,
and initiating the configure mode. Configure mode can be initiated by entering the configure command in
operational mode. All changes to the network configuration are done to a copy of the active configuration.
These changes do not take effect until a successful commit or commit confirm command is entered.
NSO organizes all managed devices as a list of devices. The path to a specific device is devices device
DEVICE-NAME.
The CLI provides two modes of operation. When prepended with > it indicates operational mode. When
prepended with % it indicates the configuration mode.
> Operation mode: fetches operational data from the network devices like interface statistics, and also
operational data that is maintained by NSO like alarm counters.
% Configuration mode. Show configuration data for all devices: this is done before we have loaded the
configuration from the real devices in the network to NSO.

NSO and YANG
 NSO has it‘s own YANG models: tailf-ncs-*.yang
 The NSO YANG model can be augmented
 tailf-ncs-devices.yang references a flat list of devices
 A device is identified by a free form text string
container devices {
tailf:info "The managed devices and device communication settings";
uses connect-grouping {
augment "connect/input" {
leaf-list device {
tailf:info "Only connect to these devices.";
type leafref { path '/devices/device/name'; }
}
}
}
}
Each managed device is uniquely identified by a free form text string. This would typically be the Domain
Name Server (DNS) name of the managed device but could equally well be the string format of the IP
address of the managed device or anything else. Furthermore, each managed device has a mandatory IP/port
pair that together with the authgroup leaf provides information to NSO how to connect and authenticate over
Secure Shell (SSH)/NETCONF to the managed device. Depending on the device-type NSO speaks different
protocols southbound.
The following 4 device types are available:
 NETCONF - This is the default if no device-type is specified.
 CLI - The NSO CLI-NED is used to speak to the device. This requires YANG models with the
appropriate annotations for the device CLI.
 SNMP - The device speaks SNMP, preferably in read-write mode.
 Generic NED - User java code needs to be present between NSO and the device to perform the
translation of operations to and results from the device.
The empty container /ncs:devices/device/config is used as a mount point for the YANG models from the
different managed devices. Whenever we wish to manage a device, we need access to the YANG models for
the device. We need to explicitly import the YANG models for each type of device using the nso compiler
(ncsc).
Devices and Device YANG Models
 To manage a device, we need a corresponding YANG model
 Device models a are deployed as part of NED packages
 All imported modules appear under /devices/device/config in the CDB
The empty container /NSC:devices/device/config is used as a mount point for the YANG models from the
different managed devices. Whenever we wish to manage a device, we need access to the YANG models for
the device. We need to explicitly, using the ncsc, import the YANG models for each type of device.

Device Configuration Management
This topic explains how NSO Device Manager manages network device configuration.
Synchronizing from Device

 Device Configurations in NSO and actual Device Configuration should match
 After initial device discovery or import, it makes sense to synchronize
configurations from devices
sync-to
admin@nso# devices sync-from sync-from
check-sync
sync-result { compare-config
device lb0 Cisco
NSO
result true
}
When the NSO daemon is running and we have initialized the daemon with IP/Port and authentication
information as well as imported all modules we can start to actually manage devices through NSO.
NSO provides the ability to synchronize the configuration to or from the device. If we feel that the device has
the correct configuration we can choose to synchronize from a managed device whereas if we feel that NSO
has the correct device configuration and the device is wrong, we can choose to synchronize from NSO to the
device. In the normal operation, the configuration on the device and the copy of the configuration inside
NSO should be identical.
Synchronizing to Device
 When a device has been configured out of band
 Clears up rogue configuration
 “dry-run” option available to check changes sync-to
sync-from
admin@nso# devices device PE11 sync-to check-sync
compare-config
result true Cisco
NSO
Change device
configuration over CLI.
Synchronizing from NSO to the device is common when we realize that a device has been configured out of
band. NSO has no means to enforce that devices are not directly reconfigured behind the back of NSO.
However it has means to discover this. This will happen automatically when a transaction will try to change
the device configuration. The transaction will fail due to configurations being out-of-sync. The configuration
verification can also be done manually using the check-sync command. When the configuration is out-of-
sync it may (or may not, depending on the situation at hand) make sense to synchronize from NSO to the
device, i.e. undo the rogue reconfigurations. A dry-run option is available for the sync-to commands, so that
we can check what the sync command would do to the device.

Check Sync
 Check if a device has been configured out of band
admin@nso# devices check-sync
sync-result {
device PE11
result in-sync
}
...
 Check if a subset of managed devices has been configured out of band

admin@nso# devices device PE1..9 check-sync
devices device PE1 check-sync
result in-sync
result in-sync
When managing large networks with NSO a good strategy is to consider the NSO copy of the network
configuration to be the main master copy. All device configuration changes must go through NSO and all
other device re-configurations are considered rogue.
NSO doesn't contain any functionality which disallows rouge re-configurations of managed devices, however
it does contain a mechanism to discover if one or several devices have been configured out of band.
Comparing Configuration
 Compare out-of-sync device configuration
admin@nso(config)# devices device PE11 check-sync
result out-of-sync
info got: 334bb33aae40155831edfa0b6a978f39 expected: a1424cd35da4499f6a71b3d38ae648a8
admin@nso(config)# devices device PE11 compare-config “-” represents configuration items

diff
devices {
that should be deleted from the
device PE11 { CDB in order to be the same as on
config {
ios:interface { the device
Loopback 10 {
ip {
address {
primary { “+” represents configuration items
- address 10.1.1.1;
+ address 2.2.2.2;
that should be added to the CDB
} in order to be the same as on the
}
} device
If the device is not in sync, we are interested to know what the difference is. The CLI sequence above shows
how to do an explicit configuration comparison.
The “-” sign represents configuration items that should be deleted from the CDB in order to be the same as
on the device.
The “+” sign represents configuration items that should be added to the CDB in order to be the same as on
the device

Displaying Configuration
 Display only new parts of configuration:
admin@nso# config
admin@nso(config)# devices device PE11 config ios:interface Loopback 20
admin@nso(config-if)# ip address 10.2.2.2 255.255.255.255
admin@nso(config-if)# show configuration
devices device PE11
config
ios:interface Loopback30
 Display full configuration
ip address 10.3.3.3 255.255.255.255 Displays current configuration items in
no shutdown
exit
the current configuration mode
!
!
admin@nso(config)#
The show configuration command will display the current configuration items in the current configuration
mode. In the example, you may note that we have configured two Loopback interfaces but the show
configuration command only displays the last one. The reason for that is that we are currently in the
Loopback 30 configuration mode.
Displaying Configuration (Cont.)
 Display only new parts of configuration:
admin@nso(config-if)# top
admin@nso(config)# show configuration
devices device PE11 Go to root of the data tree to display
config the all configuration items of the
ip address 10.1.1.1 255.255.255.255 configuration session
no shutdown
exit
 Display full configuration
ip address 10.3.3.3 255.255.255.255
no shutdown
exit
!
!
The continuation of the example shows how we can move to the top of the CDB data tree and issue the show
configuration command again. This time it will display all configuration of the current configuration
session.

Displaying Configuration
 Display entire CDB:
admin@nso# show running-config
or
admin@nso(config)# show full-configuration
 Display portion of CDB:

admin@nso# show configuration devices device PE11 config ios:interface Loopback
devices device PE11
config
ip address 10.1.1.1 255.255.255.255
no shutdown
...
The show running-config command can be extended by specifying the part of the CDB to display.
Configuring Devices
 Configuration change happens after final commit statement
admin@nso# config
admin@nso(config)#
admin@nso(config-if)# commit
admin@nso#
It's possible to configure several devices through the NSO inside the same network transaction. The above
command was a multi host transaction. In the same transaction we re-configured three hosts. Had one of
them failed, or been non-operational, the transaction as a whole would have failed. The default re-
configuration behavior is to try to manipulate the candidate configurations of the managed devices (assuming
they support the candidate NETCONF capability). This is a two phase commit procedure. We start by
sending NETCONF edit-config commands to the managed devices. Assuming they all accept the edit-config
RPCs, we validate on all devices (if they support it). Then we continue by committing to each device. In the
ideal scenario, all participating devices support the confirmed commit capability. On all devices that support
the confirmed commit capability, NSO issues a confirmed commit RPC. If all involved devices accept the
confirmed commit, we issue the final confirming commit. This way NSO ensures network wide transactional
consistency.

Candidate Support
 NSO works with devices that do not support NETCONF candidate
 NSO simulates candidate capability for these devices using NEDs
 NSO divides devices in the following groups:
Candidate
 start_trans_running Configuration
 lock_candidate Running session
 lock_reset_candidate Cisco Minimal

NSO
 startup diff
 running-only
Edit config
NSO reads the capabilities of each managed devices and executes completely different sequences of
NETCONF commands towards different types of devices.
For implementations of the NETCONF protocol that do not support the candidate configuration, and in
particular devices that do not support NETCONF commit with a timeout, NSO uses other means to cope with
the device. NSO announces candidate support and also confirmed commit capability on its northbound
NETCONF interface regardless of the capabilities of the managed devices. Simple devices that do not
support candidate configurations are handled regardless, and NSO simulates the semantics of these more
advanced NETCONF features.
NSO divides devices in the following groups:
 start_trans_running - This mode is used for devices that support the Tail-f proprietary transaction
extension defined by http://tail-f.com/ns/netconf/transactions/1.0. Read more on this in the Tail-f ConfD
user guide. In principle it's a means to - over the NETCONF interface - control transaction processing
towards the running data store. This may be more efficient than going through the candidate data store.
The downside is obviously that it is Tail-f proprietary non-standardized technology.
 lock_candidate - This mode is used for devices that support the candidate data store but disallow direct
writes to the running data store.
 lock_reset_candidate - This mode is used for devices that support the candidate data and also allow
direct writes to the running data store. This is the default mode for Tail-f ConfD NETCONF agent.
Since the running data store is configurable, we must, prior to each configuration attempt, copy all of
running to the candidate. (ConfD has optimized this particular usage pattern, so this is a very cheap
operation for ConfD)
 startup - This mode is used for devices that have writable running, no candidate but do support the
startup data store. This is the typical mode for Cisco like devices.
 running-only - This mode is used for devices that only support writable running.
Which category NSO chooses for a managed device depends on which NETCONF capabilities the devices
sends to NSO in its NETCONF hello message.
Confirmed Commit Support
 Not all devices support confirmed-commit:1.0 standard NETCONF capability
 NSO is able to work around that drawback
 Possible failure scenarios could include:
 Operator aborts the network wide transaction or connectivity to one of the devices is
lost: NSO sends the reverse diff
 The device rejects the configuration: NSO aborts the transaction
 NSO experiences a timeout: connectivity needs to be restored and configuration
synched from NSO
Another important discriminator between managed devices is whether they support the confirmed commit
with a timeout capability, i.e. the confirmed-commit:1.0 standard NETCONF capability. If a device supports
this capability, NSO utilizes it. This is the case with for example Juniper routers. If a managed device does
not support this capability, NSO uses NEDs to work around that problem.
In certain situations the following failure scenarios could occur:
 The operator aborts the transaction, or NSO loses the SSH connection to another managed device which
is also participating in the same network transaction. In this case, NSO has the revert diff and simply
sends the precise undo information to the device. If the device does support the confirmed-commit
capability, NSO aborts the outstanding yet-uncommitted transaction simply by closing the SSH
connection. In this case, NSO sends the reverse diff instead.
 The device rejects the transaction in the first place, i.e. the NSO attempt to modify its running data store.
This is an easy case since NSO then simply aborts the transaction as a whole in the initial commit
confirmed [time] attempt.
 NSO loses SSH connectivity to the device during the timeout period. This is a real error case and the
configuration is now in an unknown state. NSO will abort the entire transaction, but the configuration of
the failing managed device is now probably in error. The correct procedure once network connectivity
has been restored to the device is to sync it in direction from NSO to the device. The NSO copy of the
device configuration will be what was configured prior to the failed transaction.
Even if not all participating devices have first class NETCONF agent implementations, NSO will attempt to
simulate the confirmed-commit capability.

Configuration Flow Example – External OSS Integration
1. To NSO: OSS/BSS
 EDIT-CONFIG candidate
 VALIDATE candidate
2. To the Devices:
 LOCK running 1. EDIT-CONFIG
 LOCK candidate
Cisco
 EDIT-CONFIG candidate NSO
 VALIDATE
 CONFIRMED-COMMIT
 COMMIT
 UNLOCK running 2. LOCK, COMMIT, ...
 UNLOCK candidate
3. To NSO:
 COMMIT running
3. COMMIT
The diagram lists the configuration flow sequence. In this example operations support system (OSS) uses
NETCONF to communicate with the NSO – the NSO provides the network abstraction and the OSS
configures the network itself through NSO instead of dealing with specific devices. The NSO runs
NETCONF or simulates NETCONF-like behavior towards devices. It locks their running and candidate
configurations and makes and validates the appropriate changes. Then it waits for confirmation from the
devices and finally commits the configuration before unlocking both candidate and running configurations.
Note that NSO can easily integrate with an existing/new OSS. Since NSO can also serve as an OSS, this is
just one of deployment scenarios.
Error Recovery
 Devices that do not have confirmed commit support
 One of the devices fails to commit
 NSO tries to mimic the confirmed commit
 Rollback strategy is:
 Retrieve device configuration
 Compare with desired configuration
 Calculate the diff
 Apply the commands in diff
On devices that do not support confirmed commit, an error recovery mechanism is necessary. Once we have
started to commit, there is no turning back. If a device rejects the commit or dies between the edit-config
RPC and the commit RPC, we have a failure scenario where the network and NSO are out of sync. This may
sound harsh, but it's the way two-phase commit works. The manager asks all participants if they accept the
proposed change, they all acknowledge the proposed change. The manager then initiates the commit - if then
one of the participants fails to commit, NSO and that managed device are out of sync. NSO goes to great
lengths mimicking the semantics of confirmed commit towards devices that are less capable. The strategy to
roll back a less capable device is to first retrieve the entire configuration from the device, then compare that
configuration to the desired config, calculate the diff, and then finally issue the commands that are the result
of the diff calculation to the device. The reason for this strategy, is that for non-NETCONF capable devices
we cannot know for sure how much of a proposed configuration change to the device was actually accepted.

Rollbacks
 Every transaction has a corresponding rollback file:
admin@nso:~/ncs-run/logs$ ls rollback*
admin@nso:~/ncs-run/logs$ more rollback10155 Displays what NSO did
admin@nso# show configuration commit 10157
devices device PE11
config
no ios:interface Loopback10
! Displays what NSO would
! do if you execute a rollback
admin@nso# show configuration rollback 10157
!
! Created by: admin
! Date: 2016-01-14 14:40:58
! Client: cli
!
devices device PE11
config
ip address 10.1.1.1 255.255.255.255
no shutdown
NSO keeps the changes made by the latest transactions in a form of a rollback file. This means that every
configuration can simply be revoked by rolling back the corresponding transaction.
Rollbacks – Examples
 Rollback 3 latest transactions (last change ID is 10157):

admin@nso(config)# rollback 10155
 Rollback only changes done in 3rd latest transaction:

admin@nso(config)# rollback selective 10155
 Rollback dhcp changes on PE11 in the 3 latest transactions:

admin@nso(config)# rollback 10155 devices device PE11 config ios:interface
 Rollback dhcp changes on PE11 in the 3rd latest transaction:

admin@nso(config)# rollback selective 10155 devices device PE11 config ios:interface
The transaction can be rolled back all the way or selectively. Selectively means we can only roll back a part
of a transaction, that part being either:
 Configuration for a specific device.
 Configuration for a specific network function.
 A combination of the above.
 The roll back of a previous end-to-end service configuration? When an end-to-end service configuration
is rolled back to previous state, only changes done by that single transaction (ignores any changes done
by other transactions). This is also called a selective rollback.

Meta Configuration – Single Device
admin@nso(config)# devices device PE11 Highlighted parameters represent the
minimum required configuration for a device
address - IP address or host name for the management interface
authgroup - Authentication credentials for the device
config - NCS copy of the device configuration
connect-timeout - Timeout in seconds for new connections
description - Free form textual description
device-type - Management protocol for the device
live-status-protocol - Additional protocols for the live-tree (read-only)
location - Physical location of devices in the group
netconf-notifications - NETCONF notifications from the device
port - Port for the management interface
read-timeout - Timeout in seconds used when reading data
remote-node - Name of remote node which connects to device
snmp-notification-address - Notification address if different from device address
source - How the device was added to NCS
state - Show states for the device
trace - Enable trace for this device
write-timeout - Timeout in seconds used when writing data
Apart from actual device configurations that NSO also holds meta configuration data for devices. This meta
configuration includes settings necessary for managing the device and is important for the actual NSO.
The above syntax lists all possible completions for meta configuration change for a single device.
Meta Configuration – All Devices
admin@nso(config)# devices global-settings
commit-queue - Enables and configures the commit-queue
commit-retries - Retry commits on transient errors
connect-timeout - Timeout in seconds for new connections
ned-settings - Control which device capabilities ncs uses
out-of-sync-commit-behaviour - Specifies the behaviour of a commit operation involving a device that is
out of sync with ncs.
read-timeout - Timeout in seconds used when reading data
report-multiple-errors - By default, when the ncs device manager commits data southbound and when
there are errors, we only report the first error to the operator, this
flag makes ncs report all errors reported by managed devices
session-pool - Control how sessions to related devices can be pooled.
ssh-keep-alive - Controls SSH keep alive settings
trace - Trace the southbound communication to devices
trace-dir - The directory where trace files are stored
write-timeout - Timeout in seconds used when writing data
Like all configurations, meta configuration changes can be done for a separate device, a group of devices or
globally for all devices.

Device Action – All Devices
admin@nso# devices ?
check-sync - Check if the NCS config is in sync with the device
check-yang-modules - Check if NCS and the devices have compatible YANG modules
clear-trace - Clear all trace files
commit-queues - List of queued commits
connect - Set up sessions to all unlocked devices
device - The list of managed devices
device-group - Groups of devices
disconnect - Close all sessions to all devices
sync - DEPRECATED - use sync-to or sync-from instead
sync-from - Synchronize the config by pulling from the devices
sync-to - Synchronize the config by pushing to the devices
There are device specific actions that can be applied to all devices or a selected group of devices at once.
Installed Device Models (NEDs)
admin@nso# show devices device-module | tab
NAME URI DEVICES
------------------------------------------------------------------------------------------------------------
tailf-ned-cisco-ios urn:ios [ PE12 PE11 CE22 CE21 CE12 CE11 ]
tailf-ned-cisco-ios-stats urn:ios-stats [ PE12 PE11 CE22 CE21 CE12 CE11 ]
tailf-ned-cisco-ios-xr http://tail-f.com/ned/cisco-ios-xr [ P11 P12 P21 PE21 PE22 PE31 PE41 ]
tailf-ned-cisco-ios-xr-stats http://tail-f.com/ned/cisco-ios-xr-stats [ P11 P12 P21 PE21 PE22 PE31 PE41 ]
 List device types

 List devices per each device type
It is important that the YANG models for managed devices are imported into NSO. Check the devices and
their NEDs using show devices device-module command.

Configured Devices
admin@nso# show devices list
NAME ADDRESS DESCRIPTION NED ID ADMIN STATE
--------------------------------------------------------
P11 127.0.0.1 - cisco-ios-xr unlocked
PE11 127.0.0.1 - cisco-ios unlocked
PE12 127.0.0.1 - cisco-ios unlocked
PE21 127.0.0.1 - cisco-ios-xr unlocked
 List devices with basic parameters

 Device address and description
 NED ID
 Administrative state
Another useful command to list all devices and their state is the show devices list command. It includes the
name of the device, the address at which it is managed, the description (if specified), the NED ID and the
administrative state.
Device Connection Management
This topic describes how device connection is obtained and maintained.
Device States
Oper State Description
Enabled Device is reachable from NSO.
Disabled Device is unreachable from NSO
Admin State Description

Southbound-locked (default) Configuration change is possible
not pushed to the device.
Locked Configuration change is not
possible.
Unlocked Configuration change is possible
and pushed to the device.
NSO differentiates between oper state and admin state for a managed device. Oper state is the device
connectivity state and should reflect the actual state of the device. A managed device oper state is either
enabled or disabled. The admin state relates to the possibility of changing the device configuration and is
usually set manually.

Oper State
 The actual state of a managed device
 It is either ‚enabled‘ or ‚disabled‘
 If NSO initiates operations and the device is unreachable the oper state is set to
disabled
Cisco
NSO
SSH not possible

= disabled
SSH is up
= enabled
Oper state can be mapped to an alarm for the device. If the device is disabled, we may have additional error
information. If we manually stop a managed device, NSO doesn’t consider the device as non-operational
immediately. The only certain method for NSO to know that a managed device is non-operational is that it
cannot SSH connect to it. NSO cannot draw any conclusions from the fact that a managed device closed its
end of the SSH connection. It may have done so because it decided to time out an idle SSH connection. If we
try to initiate any operations towards the dead device, the device will be marked as oper state disabled.
Admin State
 Southbound-locked (default): possible to manipulate the configuration but
changes are never pushed to the device
 Locked: all changes to device are forbidden
 Unlocked: this is the state we set a device into when the device is operational. All
changes to the device will be sent southbound
Cisco Configure PE11
NSO
Configure PE12
Configure PE21
PE11: unlocked – PE12: unlocked - PE21: locked –

Configuration changed Configuration transaction FAILS
changed
We have three different admin states for a managed device:

 Southbound-locked - This is the default value. It means that it is possible to manipulate the
configuration of the device but config changes done to the devices are never pushed. This mode is
useful during e.g. pre-provisioning, or when we instantiate new devices.
 Locked - This means that all changes to device are forbidden. Any transaction that attempts to
manipulate the configuration of a locked device will fail. It is still possible to read the configuration of a
locked device.
 Unlocked - This is the state we set a device into when the device is operational. All changes to the
device will be sent southbound.

Adding a Device
1. Manually: useful for small number of devices (e.g. development and testing)
2. Cloning: replicate a device from an existing device
3. Templates: replicate a device from a template
4. Bulk upload: useful for initial definition of many devices
admin@nso(config)# devices device PE101 address 10.1.1.1
admin@nso(config-device-PE101)# device-type cli ned-id cisco-ios protocol ssh
admin@nso(config-device-PE101)# authgroup default
admin@nso(config-device-PE101)# commit
Commit complete.
Apart from the discovery module a device can also be added manually. This requires to specify the following
device parameters at minimum:
 IP address
 Device Type
 Corresponding NED (YANG model)
 Access Protocol
 Authentication Group
Two additional methods of adding a device to NSO exists: using cloning or templates.
Cloning a Device
 Devices can be instantiated from other devices
 These devices can be immediately configured
 All configuration succeeds within NSO and nothing is sent to devices
(southbound-locked state!)
 All device configuration is cloned!
admin@nso(config)# devices device PE12 instantiate-from-other-device device-name PE11

admin@nso(config)# commit
Commit complete.
We can add new devices by cloning an existing device. Say we have hundreds of CE routers with known
good configuration and another one needs to be added to NSO. We can do that by cloning one of the existing
CE routers and the new device will be immediately available within NSO with the same settings. The cloned
device is southbound locked. This is a mode where we can reconfigure a device, but any changes done to it
are never sent to the managed device.

Create a Device Using Templates
 Devices can be instantiated from templates
 These devices can be immediately configured
 All configuration succeeds due to southbound-locked state
 Only template specific configuration is applied
admin@nso(config)# devices device www5 address 127.0.0.1 port 23456 authgroup default
admin@nso(config)# devices device www5 apply-template template-name std-web-server
A more attractive alternative to instantiating a device from the actual working configuration of another
device is to have a number of named template configurations that we can use. Compared to device cloning,
this approach is much more flexible and will only set the device parameters specified by the template.
Load Using „ncs_load“ Command
 A convenient way of loading and saving configuration
 ncs_load without any options it will print the current configuration
 Load (-l) option uploads XML contents to the CDB
 Merge (-m) option updates the existing device list
 Example of uploading and merging configurations of Netsim devices to NSO:
admin@nso:~$ ncs-netsim ncs-xml-init > devices.xml
admin@nso:~$ ncs_load -l -m devices.xml
Make sure you use the -m option to merge the XML contents with
the CDB. The default action is replace which would delete the
entire CDB and replace it with the XML contents!
This command provides a convenient way of loading and saving all or parts of the configuration in different
formats. It can be used to initialize or restore configurations as well as in CLI commands. If you run
ncs_load without any options it will print the current configuration in XML format on stdout. The exit status
will be zero on success and non-zero otherwise.
If we have already started NSO with an XML initialization file for the existing network, an updated
initialization file will not take effect unless we remove the Configuration Database (CDB) files, losing all
NSO configuration. But we can replace the original initialization data with data for the complete new
network when we have run add-to-network, by using ncs_load while NSO is running.

Templates and Groups
This topic describes how the concepts of templates and groups are used in device management.
Authgroups
 NSO requires SSH credentials to access a device
 Named authgroups are used to map NSO user to device credentials
admin@nso# show running-config devices authgroups
devices authgroups group default
umap admin Cisco
NSO
remote-name admin
remote-password $4$wIo7Yd068FRwhYYI0d4IDw== Login as admin
!
umap oper Maps to username
remote-name oper on device
remote-password $4$zp4zerM68FRwhYYI0d4IDw==
!
!
When NSO connects to a managed device, it requires the SSH authentication information for that device.
Named authgroups are used to decide how to map a local NSO user to remote authentication credentials on a
managed device. The list 'group' is used for NETCONF and CLI managed devices. The list 'snmp-group' is
used for SNMP managed devices. When NSO connects to a managed device, it locates the authgroup
configured for that device. Then NSO looks up the local NSO user name in the 'umap' list. If an entry is
found, the credentials configured is used when authenticating to the managed device. If no entry is found in
the 'umap' list, the credentials configured in 'default-map' are used. If no 'default-map' has been configured,
and the local NSO user name is not found in the 'umap' list, the connection to the managed device fails.
Device Groups
 NSO requires SSH credentials to access a device
 Named authgroups are used to map NSO user to device credentials
admin@nso(config)# devices device-group "PE Routers"
admin@nso(config-device-group-routers)# device-name PE1..9
admin@nso# devices device-group routers sync-from
Create device group

Cisco
NSO “PE Routers”
Perform sync-from action on
device group “PE Routers”
PE11 PE12 PE21
The NSO Device Manager has a concept of groups of devices. A group is nothing more than a named group
of devices. What makes this interesting is that we can invoke several different actions on the group, thus
implicitly invoking the action on all members in the group. This is especially interesting for the apply-
template action and synch actions. The definition of device groups reside at the same level in the NSO data
model as the device list.

Template Types
 Device-templates
 Manipulate device configuration data
 Config-templates:
 Manipulate any part of the configuration
 Stored within a package
Usage Device-Template Config-Template

In Actions Yes No
In Services No Yes
Through API No Yes
Both device-templates and config-templates are based on the same principles and are interpreted the same
way. The difference is how they are stored and in what context they can be applied.
Two different types of templates exists:
 Device-templates: These templates are part of the NSO configuration. Device-templates are created and
changed in the tree /devices/template/config the same way as any other configuration data and are
affected by rollbacks and upgrades. Device-templates can only manipulate configuration data in the
/devices/device/config tree i.e. only device data.
 Config-templates: These templates gets loaded as part of packages. The config-templates are stored in
XML files in the templates sub directory of a package. Config-templates can be used to update any part
of the configuration.
The different types of templates can be used for different purposes. Basically the two types are the same but
they are stored in different ways and manipulated in different ways. It is easy to convert from one type to
another.
Templates
 Used to apply snippets of configuration Templates can hold
Create template: configuration for multiple device
admin@nso(config)# devices template NTP_DNS config
admin@nso(config-config)# ios:ntp server peer-list 10.0.0.1
types – NSO knows which part
admin@nso(config-server-list-10.0.0.1)# exit to use with which device
admin@nso(config-config)# ios:ip domain name cisco.com
admin@nso(config-config)# ios:ip name-server 198.18.133.1
admin@nso(config-config)# cisco-ios-xr:ntp server server-list 10.0.0.1
admin@nso(config-server-10.0.0.1)# exit
admin@nso(config-config)# cisco-ios-xr:domain name cisco.com
admin@nso(config-config)# cisco-ios-xr:domain name-server 198.18.133.1
admin@nso(config-config)# top
Apply to new or existing device:

admin@nso(config)# devices device-group "PE Routers" apply-template template-name NTP_DNS
Templates can also be used to apply snippets of configuration. Templates are a flexible and powerful
mechanism in NSO which simplifies how changes can be made across the configuration data, for example
across devices of different type. They also allow a declarative way to describe such manipulations.

Templates with Variables
 Variable needs to be provided with a value:
admin@nso(config)# devices template SHAPE config
admin@nso(config-config)# ios:policy-map SHAPE
admin@nso(config-ios:policy-map-SHAPE)# class class-default
admin@nso(config-class-class-default)# shape average bit-rate {$BPS}
admin@nso(config-class-class-default)# commit
 Apply the template by providing variable values:

admin@nso(config)# devices device-group "PE Routers" apply-template template-name SHAPE variable { name BPS value '1000000' }
admin@nso(config)# show configuration
devices device PE11
config
ios:policy-map SHAPE
! first
class class-default
shape average 1000000
!
!
!
!
...
Each value in a template is stored as a string. This string value is converted to the actual value type of the
YANG model when the template is applied.
Request devices device c1 apply-template template-name servers-static variable { name DNS_SERVER
value '192.168.2.14' } this would result in the value '192.168.2.14' being set to the dns server of device c1,
conversion from string to an actual IP Address will occur when the value is assigned.
XPath 1.0
 Language for selecting nodes inside XML documents
 Can be used to compute values based on on XML content
 Used to navigate through XML tree structure
 Nodes are selected based on criteria. For example @ipaddr would select all interface
ip addresses within the XML below
<?xml version="1.0" encoding="utf-8"?>
<router>
<interfaces>
<interface ipaddr="10.1.1.1">FastEthernet0</interface>
</interfaces>
</router>
XPath 1.0 is a language for navigating within XML documents and can also be used to make computations
using the values stored in the XML document. XML can be represented using a tree structure and XPATH is
used to navigate through that structure.

Templates with Variables Using XPath
 The expression may be more complex than just a variable reference (XPath 1.0)
{$iftype+$ifnum}
{mtu-$header_len}
{../diameter*3.14}
{/devices/device[name='www2']/config/interface[name='eth0']/speed
 Value enclosed in single quotes is a string XPath expressions can be

 Value without single quotes is an XPath 1.0 expression used in template definitions
admin@nso(config)# devices template SHAPE config or when applying templates
admin@nso(config-config)# ios:policy-map SHAPE
admin@nso(config-ios:policy-map-SHAPE)# class class-default
admin@nso(...)# shape average bit-rate {/devices/device[name=$DEV]/config/ios:interface/GigabitEthernet[name='0/1']/speed*1000}
admin@nso(...)# commit
admin@nso(config)# devices device PE11 apply-template template-name SHAPE variable { name DEV value 'PE11'}
XPath supports variables in addition to the typical operators, filters and functions. The example illustrates the
usage of variables and multiplication in an XPath expression where the speed in kbps is converted into QoS
configuration requiring a value in bps.
Policies
 The Device and Service models contain constraints that always must be true
 You might want to add constraints at run-time
 Example: a certain interface on the device must be available
admin@nso(config)# policy rule Loop0
admin@nso(config-rule-Loop0)# foreach /devices/device[name='PE11']
admin@nso(config-rule-Loop0)# expr config/ios:interface/Loopback[name=0]
admin@nso(config-rule-Loop0)# error-message "Loopback0 is Mandatory"
 Try removing the interface for which you have a constraint:

admin@nso(config)# devices device PE11
admin@nso(config-device-PE11)# config
admin@nso(config-config)# no ios:interface Loopback 0
admin@nso(config-config)# commit
Aborted: Loopback0 is Mandatory
admin@nso(config-config)#
Policies allow you to specify network wide constraints that always must be true. If someone tries to apply a
configuration change over any northbound interface that would evaluate to false the configuration change is
rejected by NSO. Note that any configuration can be activated and deactivated. This means that in order to
temporarily turn off a certain policy you can deactivate it. Note also that if the configuration was changed by
any other means than NSO by local tools to the device like a CLI, a sync-from-device operation might fail if
the device configuration violates the policy.

Other Device Management Tools
This topic introduces some of the other tools used in device management.
Commit Queues
 If one of the devices configured within a transaction is offline, the whole
transaction fails
 This may not always be desired functionality!
 Commit queues can be used to mitigate this
 Transaction will succeed for Cisco
NSO Commit
non-responding devices
 The configuration for the RESULT: SUCCESS
device will get queued RESULT: Commit Queued
 NSO will repeatedly try to
push that configuration to the Device Offline
device RESULT: SUCCESS!
 Do not confuse this with
invalid configurations
The concept of transactions eliminates best-effort configuration attempts. Either all configurations on all
devices succeed and are committed or the whole transaction fails and no changes are committed to the
network. Because NSO needs to wait for all devices to commit the configuration changes, this process can
become slow, especially when you have devices that are currently not responding. They are either offline or
inaccessible for other reasons. It may make sense to have a mechanism that handles this. This will be
separate the invalid configurations from devices that explicitly indicated an error from devices that are not
responding. This means that the transaction will only fail when the device explicitly indicates an error. If it is
simply unreachable, the changes will be backlogged in NSO but the transaction itself will still succeed.
Commit Queues (Cont.)
 Default behavior: an all-or-nothing network wide transaction
 Alternative behavior using commit queues:
 Synchronous commit:
admin@nso(config)# commit sync-commit-queue
 Asynchronous commit:
admin@nso(config)# commit sync-commit-queue
 Change default to use commit queues:

admin@nso(config)# devices global-settings commit-queue enabled-by-default true
One of the strengths on NSO is the concept of "network wide transactions". When we commit data to NSO
that spans multiple devices in the /devices/device tree, NSO will commit the data on all devices or none. The
downside of this is that the slowest device in each transaction limits the overall transactional throughput
through NSO. In NSO deployments scenarios where we wish to have higher transactional throughput than
what is possible using "network wide transactions", we can use the commit queues instead. Typically when
automation software north of NSO generates network change request it may very well be the case that more
requests arrive than what can be handled. Note, that the choke point in the majority of the cases will be the
devices, not NSO itself.
Another use case where we can use the commit queues is when we wish to push a configuration change to a
set of devices and we don't care about weather all devices accept the change or not. We do not want the
default behavior for transactions which is to reject the transaction as a whole if one or more participating
devices fail to process its part of the transaction.
When a transaction arrives at the system, NSO will split up the transactional content on a per managed
device basis. By default, NSO will - within the NSO transaction - send the data to each participating device.
The NSO transaction doesn't return until all participants have acknowledged the proposed configuration
change. With commit queues, NSO will compute the configuration change for each participating device, put
it in an outbound queue and immediately return. The queues are then independently run. The upside of this
scheme is that the transactional throughput through NSO is considerably higher. The downsides are:
 If a device rejects the proposed change, NSO and the device will be out of sync. Whenever this happens,
an NSO alarm (called commit-through-queue-failed) is generated.
 While a transaction remains in the queue, i.e. it has been accepted for delivery by NSO but is not yet
delivered, the view of the network in NSO is not (yet) correct. Eventually though, the queued item will
be delivered, thus achieving eventual consistency.
 It’s up to the Operational Manager and the Business owners to decide how important these possible
consequences are and correlate these to the business impact.

Commit Variants
 There are several ways the commit command can be used:
admin@nso(config)# commit ?
abort - Abort a pending commit
and-quit - Commit current set of changes and exit configuration mode
bypass-commit-queue - Commit directly even if commit queue exists
check - Validate current configuration
comment - Add a commit comment
confirmed - Commit current set of changes with a timeout
dry-run - Show the diff but do not perform commit
label - Add a commit label
no-confirm - Commit current set of changes, do not query user
no-networking - Send nothing to the devices
no-out-of-sync-check - Commit even if out of sync
no-revision-drop - Fail if device has too old data model
persist-id - Specify a persist-id
through-commit-queue - Commit through the commit queue
There are several ways the commit command can be used. The commit command is the one that commits the
changes to the CDB and also starts the transactions that result in device configuration change.
Pipes
 A useful tool for command output processing
admin@nso# show running-config | ?
annotation Show only statements whose annotation matches a pattern
append Append output text to a file
begin Begin with the line that matches
count Count the number of lines in the output
csv Show table output in CSV format
de-select De-select columns
display Display options
exclude Exclude lines that match
extended Display referring entries
hide Hide display options
include Include lines that match
linnum Enumerate lines in the output
match-all All selected filters must match
match-any At least one filter must match
repeat Repeat show command with a given interval
save Save output text to a file
select Select additional columns
sort-by Select sorting indices
tab Enforce table output
tags Show only statements whose tags matches a pattern
until End with the line that matches
Pipes are a useful tool for command output processing. The enable operations such as search, count and save
output to a file.
The precise list of pipe targets depends on the command executed. Some pipe targets, like select and de-
select are only available for the show command, whereas others are universally available.

Pipes (Cont.)
 Example: Cisco style begin
admin@nso# show full-configuration aaa authentication users | begin public
aaa authentication users user public
uid 1000
gid 1000
password $1$aPd72yqs$X/yK2hUy8TQIUGkCv6jlf0
ssh_keydir /var/ncs/homes/public/.ssh
homedir /var/ncs/homes/public
!
When using the Cisco style CLI you can use the well-known pipe filtering options such as begin and include.
Similarly you have Juniper style options when using the Juniper style CLI.
Pipes (Cont.)
 Example: display configuration with curly brackets
admin@nso# show full-configuration aaa authentication users | display curly-braces
user admin {
uid 1000;
gid 1000;
password $1$8KAvA4l/$nZ41qC0EH2xgEzT5pg7Tk.;
ssh_keydir /var/ncs/homes/admin/.ssh;
homedir /var/ncs/homes/admin;
}
user oper {
uid 1000;
gid 1000;
password $1$BznViZEs$w1ieVYCFKs.INR6d2Eo861;
ssh_keydir /var/ncs/homes/oper/.ssh;
homedir /var/ncs/homes/oper;
}
When reviewing configuration or configuration changes there is a useful pipe called display curly-braces.
This formats the output to use curly brackets and produces a Juniper style output.

Annotations and Tags
 Comments (annotations and tags) make large configurations easier
to read
 Configuration can be filtered
 Displaying of configuration can be controlled
 Annotations and tags can be hidden
If you have large configurations it may make sense to be able to associate comments (annotations) and tags
with the different parts. And then be able to filter the configuration with respect to the annotations or tags.
For example, tagging parts of the configuration that relates to a certain department or customer. NSO has
support for both tags and annotations. We have a specific set of commands available in the CLI for
annotating and tagging parts of the configuration. There is also a set of pipe targets for controlling whether
the tags and annotations should be displayed, and for filtering depending on annotation and tag content.
It is possible to hide the tags and annotations when viewing the configuration, or to explicitly include them in
the listing. This is done using the display annotations/tags and hide annotations/tags pipe targets. If we
wish to hide all attributes (annotations, tags and FASTMAP attributes), we can do so by using the hide
attributes pipe target. Note that annotations and tags are part of the configuration. If you add, remove or
modify an annotation or tag you need to commit the new configuration, just as you would if you have made
any other change to the configuration.
Annotations
 An annotation is a kind a comment that can be applied to any element
admin@nso# annotate devices device PE11 config ios:interface Loopback 0 "OSPF Loopback"
admin@nso# show running-config devices device PE11 config ios:interface Loopback 0
config
/* OSPF Loopback */
ip address 10.0.0.11 255.255.255.255
no shutdown
exit
!
OR
admin@ncs# show running-config | annotation "OSPF Loopback" | exclude \!
config
/* OSPF Loopback */
ip address 10.1.1.1 255.255.255.255
ip nat inside
no shutdown
exit
An annotation is a kind a comment that can be applied to any element.

Tags
 A tag is also a type of annotation (single word)
 There can be multiple tags on an element
admin@nso# tag add devices device CE11 POP1 PE11
admin@nso# show configuration devices device
/* Tags: PE11 POP1 */
devices device CE11
/* Tags: PE21 POP2 */

devices device CE21
...
A tag is very similar to annotations with a single difference – multiple tags can be applied to an element and
a tag is limited to one word.
Template Tags
 Tags with a specific purpose
 They define how a template behaves when applied
 merge | replace | create | nocreate | delete
admin@nso# tag add devices template loop config ios:interface Loopback 0 nocreate
admin@nso# tag add devices template loop config ios:interface Loopback 0 ip replace
admin@nso# show configuration devices template | display curly-braces
template loop {
config {
ios:interface {
/* Tags: nocreate */
Loopback 0 {
/* Tags: replace */
ip {
address {
primary {
address 127.0.0.1;
}
…
The templates also allow for defining different behavior when applying the template. This is accomplished
by setting tags such as merge, replace, delete or nocreate on relevant nodes in the template.
Replace tag means that when we apply the template, once we see a tag replace, we stop merging and start
replacing instead. Another tag we can use to annotate the template is nocreate. If we annotate the template
with the nocreate tag, the merge will only affect things that already exist in the target. It will never create the
node with this tag, or anything below it. It will only modify existing structures. Nodes can also be tagged
with delete. This means that when the template is applied, these nodes are deleted from the device, if they
exist. By default, configuration is merged and/or created.

Summary
 The Device Manager is at the heart of NSO. It‘s job is to divide the network configuration
change to configuration change on managed devices.
 NSO supports YANG and is modelled using YANG itself. Everything inside NSO is based
on YANG models.
 After initial device discovery or import, it makes sense to synchronize configurations from
devices. Synchronizing from NSO to the device is common when we realize that a device
has been configured out of band.
 NSO is designed to work with many different devices but works most optimum with
devices that support NETCONF
 Named authgroups are used to decide how to map a local NSO user to remote
authentication credentials on a managed device.
 With commit queues, NSO will compute the configuration change for each participating
device, put it in an outbound queue and immediately return.
References
 Cisco Documentation
Lesson 3-1
YANG Tutorial
Overview
This lesson builds on the knowledge gained in the YANG overview lesson. In addition to
providing more information about YANG, this lesson also introduces the Network Services
Orchestrator (NSO) system and how YANG is used within the NSO architecture.
Objectives
 Understand Cisco NSO Software Architecture
 Create service packages
 Create validation patterns using regular expressions
Cisco NSO YANG Architecture
This topic describes the directory structure of NSO that is of importance when creating a
service model.
Cisco NSO Directory Structure

Packages are directories that
contain all files and code
/opt/ncs/ncs-X.Y/ NSO root directory necessary to implement a NSO
function
src/ Contains system modules
packages/ Contains service and device modules
examples/ Contains independent NSO instances with sample services
Package types:
 Service packages
 NED packages
 Data provider packages
By default, NSO will be installed to /opt/ncs/ncs-X.Y directory where X.Y represents the software version
number (in case of a system install). The focus of this lesson is on the packages directory where we will be
creating new service packages.
Packages
All user code that needs to run in NSOmust be part of a package. A package is basically a directory of files
with a fixed file structure. A package consists of code, YANG modules, custom WebUI widgets etc. that are
needed in order to add an application or function to NSO. Packages is a controlled way to manage loading
and versions of custom applications.
A package is a directory where the package name is the same as the directory name. At the top level of this
directory a file called package-meta-data.xml must exist. The structure of that file is defined by the YANG
model $NCS_DIR/src/ncs/yang/tailf-ncs-packages.yang. A package may also be a tar archive with the
same directory layout. The tar archive can be either uncompressed with suffix .tar, or gzip-compressed with
suffix .tar.gz or .tgz.
Cisco NSO Architecture
/opt/ncs/ncs-X.Y/ NSO root directory
src/ Contains system modules
ncs/yang/ Contains system modules
snmp/yang/ Contains SNMP MIBs in YANG format
packages/
neds/ Contains NEDs
pkg1/src/yang
Contain service package definitions
pkg2/src/yang
 YANG definitions are located in a src/yang subdirectory

The packages directory contains at least one directory per services – the figure illustrates two service
directories where the src/yang subdirectory is used to hold the YANG service models. Additionally, you will
find the neds subdirectory where all the installed network element drivers are located.
© 2016 Cisco Systems, Inc. Service Management 3-3

Cisco NSO Service Package Architecture
/var/opt/ncs/ NSO running directory
packages/
mypkg/ Package directory
src/
yang/
mypkg.yang YANG service model
templates/
mypkg.xml Service template
Note! The figure only illustrates the files and directories important for creating a template-based service.
This lesson focuses on the simplest and fastest way of creating a service package by using templates only
without any additional Java-based programs. In order to create a package, we will focus on two main
components:
 YANG service model located in the src/yang subdirectory.
 XML device template located in the templates subdirectory.
The file layout of a package is:

<package-name>/package-meta-data.xml
load-dir/
shared-jar/
private-jar/
webui/
templates/
src/
doc/
netsim/
In this lesson the focus is on creating a service which is mostly controlled by files in the templates and src
directories.
Creating a Service Package
This topic describes the process of creating a service skeleton which consist of a number of
subdirectories and files. This is used as a starting point when creating a template-based service
package.

Create a Service Skeleton
1. Create a package skeleton 1.
2. Use the Cisco NSO CLI to configure Service Template Service Model
Skeleton File (XML) Skeleton File (YANG)
a sample service
Configure Sample Service
3. Create the service template using Cisco NSO CLI
4. Create the service model in YANG Create Service Template

(XML)
5. Compile and deploy the package
Create Service Model
(YANG)
Service Template Service Model

(XML) (YANG)

(YANG)
The remainder of this lesson will follow the package creation process as illustrated in the figure above:
 The first step is to create a package skeleton which consists of the default service package subdirectory
structure and a set of default files needed to create the package.
 The second step is to create a sample implementation of the new service using the Cisco NSO CLI.
 The third step is to create a service template which provides the necessary mapping of YANG data
model to the individual device type configuration items.
 The forth step is the creation of the YANG service model.
 The final step is to compile and deploy the service.
This topic focuses on the first step.

Step 1: Create a Package Skeleton
 Use ncs-make-package to create a development starting point from a package
template (i.e. skeleton)
 Available package templates:
 Service skeleton: template based (XML) or java based
 NED package
 Data provider package
 Options:
 Add a Web UI customization directory to the package
 Etc.
Use the ncs-make-package command to create an NSO package. The command creates an NSO package of
a certain type. For Network Element Drivers (NEDs), it creates a netsim directory by default, which means
that the package can be used to run simulated devices using ncs-netsim, i.e. that ncs-netsim can be used to
run simulation network that simulates devices of this type. The generated package should be seen as an initial
package structure. Once generated, it should be manually modified when it needs to be updated. Specifically,
the package-meta-data.xml file must be modified with correct meta data.
Packages can also be used to provide integration with external data sources (data providers).
There are other options available such as the webui used to add a WebUI customization directory to the
package, alternatively if no additional flags are chosen, it create a WebUI only package.
The focus of this lesson, however, is to create a simple template-based service package.
Creating a Service Package Skeleton
cisco@nso:~/nso-run# cd packages/
cisco@nso:~/nso-run/packages# ncs-make-package –help
Usage: ncs-make-package [options] package-name
ncs-make-package --netconf-ned DIR package-name

ncs-make-package --snmp-ned DIR package-name
ncs-make-package --service-skeleton [java | template | java-and-template | python] package-name
ncs-make-package --data-provider-skeleton package-name
ncs-make-package --generic-ned-skeleton package-name
ncs-make-package --python-skeleton package-name
ncs-make-package --erlang-skeleton package-name
ADDITIONAL OPTIONS
--dest DIR
--build
--verbose
...
The tool can be used to create directory structure and skeleton files for:
 NEDs: generic, NETCONF
 Service packages and configuration mapping options: template, java, python or java and
template
 Data provider packages
The figure illustrates how to use the ncs-make-package command to create the subdirectory and file
structure for a template based service package.
Command Syntax for ncs-make-package

ncs-make-package [OPTIONS] package-name
Usage: ncs-make-package [options] package-name
ncs-make-package --netconf-ned DIR package-name

ncs-make-package --snmp-ned DIR package-name
ncs-make-package --service-skeleton [java | template | java-and-template | python] package-name
ncs-make-package --data-provider-skeleton package-name
ncs-make-package --generic-ned-skeleton package-name
ncs-make-package --python-skeleton package-name
ncs-make-package --erlang-skeleton package-name
ADDITIONAL OPTIONS
--dest DIR
--build
--verbose
--ncs-depend-package DIR
--vendor <String>
-h | --help
SERVICE specific options:

--augment NAME
--root-container
--java-package NAME
NED specific options:

--no-netsim
--confd-netsim-db-mode candidate | startup | running-only
NETCONF NED specific options:

--pyang-sanitize
--java-package NAME
--no-java
PYTHON specific options:

--component-name NAME
ERLANG specific options:

--erlang-application-name NAME
See manpage for ncs-make-package(1) for more info.
Step 2: Modify the YANG File
cisco@nso:~/nso-run/packages# ncs-make-package --service-skeleton template-based loopback
cisco@nso:~/nso-run/packages# cd loopback/
cisco@nso:~/nso-run/packages/loopback# ls -al
total 24
drwxr-xr-x 5 cisco cisco 4096 Oct 15 12:33 ./
drwxr-xr-x 16 cisco cisco 4096 Oct 15 12:33 ../ Create a package
drwxr-xr-x 2 cisco cisco 4096 Jun 28 12:47 load-dir/
-rw-r--r-- 1 cisco cisco 363 Oct 15 12:33 package-meta-data.xml
drwxr-xr-x 4 cisco cisco 4096 Oct 15 12:33 src/
drwxr-xr-x 2 cisco cisco 4096 Oct 15 12:33 templates/
cisco@nso:~/nso-run/packages/loopback# cd src/
cisco@nso:~/nso-run/packages/loopback/src# ls -al
total 20
drwxr-xr-x 5 cisco cisco 4096 Oct 15 12:33 ../
drwxr-xr-x 3 cisco cisco 4096 Oct 15 12:33 java/
-rw-r--r-- 1 cisco cisco 377 Oct 15 12:33 Makefile
drwxr-xr-x 2 cisco cisco 4096 Oct 15 12:33 yang/
cisco@nso:~/nso-run/packages/loopback/src# cd yang/
cisco@nso:~/nso-run/packages/loopback/src/yang# ls -al
total 12
Edit service model
-rw-r--r-- 1 cisco cisco 655 Oct 15 12:33 mypackage.yang
cisco@nso:~/nso-run/packages/loopback/src/yang# vim loopback.yang
 Preferably use an IDE for YANG which has syntax highlighting and YANG validation capability (e.g. Eclipse)
The figure illustrates the first steps in the creation of the subdirectories and files:
 Create the skeleton using the ncs-make-package command.
 Edit the package-meta-data.xml file to update the information (i.e. at least the description).
 Edit the YANG data model where you will define your service model.
(Continued on the next page)

Step 3: Modify the Template XML File
cisco@nso:~/nso-run/packages/loopback/src/yang# cd ..
cisco@nso:~/nso-run/packages/loopback/src# cd ..
cisco@nso:~/nso-run/packages/loopback# cd templates/
cisco@nso:~/nso-run/packages/loopback/templates# ls -al
total 12
-rw-r--r-- 1 cisco cisco 737 Oct 15 12:33 loopback.xml
cisco@nso:~/nso-run/packages/loopback/templates# vim loopback.xml
Edit device template
 The template maps to actual device configurations

 Contains mapping for each device type used to implement the service
Continued from previous page:

 Edit the device template where you will map your service model to the individual device type
configuration items.
 There can be one or multiple template files in a given package.
Things to Learn?
 How to build the template
 How to design a YANG service model
 Use the "top-down" or "bottom-up" approach, depending on the design
environment
Top down: Bottom up:

1. Build the YANG service model based on 1. Manually configure the new service
service description and parameters using the Cisco NSO CLI
2. Manually configure the new service 2. Export the configuration into XML
using the Cisco NSO CLI format
3. Export the configuration into XML 3. Replace exact values with variables 
format XML service template
4. Replace exact values with variables  4. Build the YANG service model around
XML service template the created template(s)
So far we identified the main components in a template-based service package that we need to manipulate in
order to create a service package. The main topics of the remainder of this lesson are how to properly create
the two most important files in the service package:
 YANG service model
 XML mapping template
The so-called bottom-up approach can be used to simplify the entire process by going from a manual
configuration of the new service, from which we extract the XML template, which in turn allows us to create
the YANG service model.

Simple Example
Cisco IOS Example Cisco IOS XR Example
interface Loopback172 interface Loopback168
ip address 10.172.19.88 255.255.255.255 ipv4 address 10.168.23.66/32
! !
Service requirements:
 Configure loopback interfaces:
 Interface number range: from 1000 to 1199
 IP address range: 10.100.x.x to 10.199.x.x
 IP mask: 255.255.255.255
 Platforms: Cisco IOS and Cisco IOS XR
Note! This example is used throughout the remainder of this lesson to illustrate how to
create a simple template-based service model.
Throughout this lesson we will use the illustrated simple service to learn how to create a template-based
service package. The first step in any service creation is its design. The sample service has the following
requirements and restrictions:
 Configure loopback interfaces on Cisco IOS and Cisco IOS XR device types.
 The interface number must be in the range from 1000 to 1199.
 The interface's IP address must be in the range from 10.100.0.0 to 10.199.255.255.
 The IP subnet mask must always be 255.255.255.255.
Informal Service Model Defining Service Parameters
Loopback
IP Address
Device Subnet Mask
IP Address
Subnet Mask
IP Address
Subnet Mask
/device
/device/loopback-intf
/device/loopback-intf/ip-address
/device/loopback-intf/mask
In order to simplify further steps it is recommended to create an informal service design where we can
visualize the data model and more importantly create a data tree that will later be used to reference the date
from the template to the YANG model.
In our example we have created a model where any router can have any number of loopback interfaces as
long as they satisfy the requirements and restrictions set for the on the previous page.

Cisco NSO CLI
This topic describes how a device template can be generated using the NSO CLI to configure a
sample service using device-specific commands.

1. Create a package skeleton
a sample service Skeleton File (XML) Skeleton File (YANG)
3. Create the service template Configure Sample Service

2.
using Cisco NSO CLI
4. Create the service model in YANG
Create Service Template
5. Compile and deploy the package (XML)

(YANG)

(XML) (YANG)

(YANG)
Once we have the informal service design created and the skeleton package ready, we can proceed to the next
step where we will first try out our designed service by implementing it manually through the Cisco NSO
CLI.
Example: Configure a Loopback Interface
admin@nso(config-if)# exit
admin@nso(config)#
admin@nso(config)# devices device PE21 config cisco-ios-xr:interface Loopback 168
admin@nso(config-if)# ipv4 address 10.168.23.66 255.255.255.255
admin@nso(config-if)# exit
 Notice that the NEDs for Cisco IOS and Cisco IOS XR expose slightly different
syntax due to different device CLIs
 Central point of management prepends another layer to the configuration
hierarchy – devices
 Repeat the service configuration step for each type of device in your environment
Let’s configure our sample service using the Cisco NSO CLI:
1. Enter configuration mode (use the conf command).
2. Configure a loopback interface on a Cisco IOS device.
3. Configure a loopback interface on a Cisco IOS XR device.
The configuration step has to be repeated for each type of device in the current environment as the
configuration syntax differs (note the difference between Cisco IOS and Cisco IOS XR).

Example: Check Candidate Configuration
admin@nso(config)# commit dry-run
device PE21 {
config {  Display candidate
cisco-ios-xr:interface {
+ Loopback 168 { configuration changes
+ ipv4 {
+ address {
+
+
ip 10.168.23.66;
mask 255.255.255.255;
 “+” indicates configuration
+ } items that will be written to
+ }
+ }
} CDB
}
}
device PE31 {  “-” indicates configuration
config {
+
ios:interface {
Loopback 1172 {
items that will be deleted
+
+
ip {
address {
from CDB
+ primary {
+ address 10.172.19.88;
+ mask 255.255.255.255;
+ }
+ }
+ }
+ }
}
}
}
Once the configuration is done, you may inspect the candidate configuration before it is pushed to the
routers. To do that you can use the commit dry-run command or the compare running brief command.
The figure show the NSO style of configuration.
Example: Check Native Configuration
admin@nso(config)# commit dry-run outformat native
device PE21
 Up-to three configuration
interface Loopback 168 verification stages:
ipv4 address 10.168.23.66 255.255.255.255
exit  Cisco NSO validation
device PE31  Device validation before
interface Loopback1172
ip address 10.172.19.88 255.255.255.255 configuration activation
exit  Device validation at
Commit complete. configuration activation time
admin@nso(config)#
 Any one of the verification stages failing will result in all changes being reverted
on all devices that were part of the same transaction
The commit dry-run command also supports output formatting options using the outformat keyword:
 cli (default): displays the NSO style configuration.
 native: displays how the configuration will be converted to the native CLI of the target device.
 xml: display how the native target device configuration can be represented in the XML format.

Example: Check XML Configuration
admin@nso(config)# commit dry-run outformat xml
device PE31 {  Display changes in XML format as a
<interface xmlns="urn:ios">
<Loopback> starting point for the service template
<name>1172</name>
<ip>
<address>  The two devices are of a different type
<primary> and therefore use a different NED
<mask>255.255.255.255</mask>
</primary>
</address>
 NEDs can be determined from the
</ip> XML namespace
</Loopback>
</interface>
}  You may also look at existing
device PE21 {
<interface xmlns="http://tail-f.com/ned/cisco-ios-xr"> configuration or active configuration
<Loopback>
<id>168</id> after it has already been committed:
<ipv4>
<address>  show devices device PE21 config
<mask>255.255.255.255</mask> cisco-ios-xr:interface Loopback
<ip>10.168.23.66</ip>
</address> 168 | display xml
</ipv4>
</Loopback>
</interface>  Important: store this output for the
}
next step – service mapping template
creation.
In our example we should record the XML format of the native configurations for the two device types that
we are using. This information will later be used to create the mapping template from the service model to
the device configuration.
In the figure, you see the service parameters being highlighted:
 Interface number
 IP address
 Subnet mask
The XML name space parameter determines the device type.
Use the commit command to deploy the configuration to the devices.
Example: Check Interface Status
admin@nso(config)# exit
admin@nso#
admin@nso# show devices device PE31 live-status interfaces Loopback ?
0 100 1172
Possible match completions:
ip-address mac-address
admin@nso#
admin@nso# show devices device PE31 live-status interfaces Loopback 1172
MAC
TYPE NAME IP ADDRESS ADDRESS
------------------------------------------
Loopback 1172 10.172.19.88/32 -
admin@nso#
admin@nso# ping 10.172.19.88
PING 10.172.19.88 (10.172.19.88) 56(84) bytes of data.
64 bytes from 10.172.19.88: icmp_seq=1 ttl=255 time=1.24 ms
64 bytes from 10.172.19.88: icmp_seq=2 ttl=255 time=0.824 ms
[ok][2014-10-28 09:26:03]
admin@nso#
 A thorough verification and testing is required to confirm that the configured sample
service can be used as a starting point for designing a service model
Once you have deployed the configuration you may verify the result. In this particular case where we have
created an addressable interface we can actually ping the target or check the existence of the newly deployed
interface on the devices.

Sample Service Configuration
 You may use live or simulated devices to create a sample native configuration
on devices
 Live testing in a lab environment is preferred as it provides a test bed where the
services can be thoroughly tested without having an impact on the production
environment
 More complex services may include a number of variations in the parameters
which will need to be considered to create a single service model that support all
required variations
Any service creation would typically be preceded by a thorough testing of the new service. Using real
devices instead of simulated devices (i.e. netsim) is recommended as it allows us to use traditional service
design approaches where thorough testing is needed to ensure proper behavior before putting the service into
production.
Service Template
This topic describes the creation of a device template that is used to map the service parameters
into a device-specific configuration.

a sample service

3. (XML)
(YANG)

(XML) (YANG)

(YANG)
Now that we have the new service deployed in a test environment and we have the native configurations in
XML format, we can proceed to the creation of the mapping template.

Creating the Service Template
cisco@nso:~/ncs-run$ cd packages/
cisco@nso:~/ncs-run/packages$ cd loopback
cisco@nso:~/ncs-run/packages/loopback$ cd templates  Edit the skeleton XML
cisco@nso:~/ncs-run/packages/loopback/templates$ ls -l service template file
total 4
-rw-r--r-- 1 cisco cisco 736 Oct 28 10:40 loopback.xml
cisco@nso:~/ncs-run/packages/loopback/templates$ more loopback.xml
<config-template xmlns="http://tail-f.com/ns/config/1.0"  Define variables in
servicepoint="loopback"> curly brackets:
<devices xmlns="http://tail-f.com/ns/ncs">
<device> {variable}
 mapped to the
<name>{/device}</name>
<config> service model:
 service model
</config>
</device> hierarchy
</devices>
</config-template>
cisco@nso:~/ncs-run/packages/loopback/templates$ vim loopback.xml
The figure illustrates the default contents of the skeleton XML file that was created by the ncs-make-
package command.
It is recommended to use all lowercase names for identifiers:
 file name (e.g. loopback.xml).
 servicepoint (e.g. "loopback"). The servicepoint should be the same as the file name without the
extension.
 The skeleton XML file already contains the device segment where there is a reference to active set of
devices.
 The skeleton XML file contains the config segment where we should add out own mapping logic for the
new service.
Example: Convert XML Configuration to Template
admin@nso(config)# commit dry-run outformat xml <config-template xmlns="http://tail-f.com/ns/config/1.0"
device PE31 { servicepoint="loopback">
<interface xmlns="urn:ios"> <devices xmlns="http://tail-f.com/ns/ncs">
<Loopback> <device>
<name>1172</name>
Variable <name>{/device}</name>
<config>
<ip>
<interface xmlns="urn:ios" tags="merge">
<address> <Loopback>
<primary>
<address>10.172.19.88</address> Variable <name>{loopback-intf}</name>
<description tags="merge">Loopback{loopback-intf}</description>
<mask>255.255.255.255</mask> <ip>
</primary> Fixed <address>
</address> <primary>
</ip> <address>{ip-address}</address>
</Loopback> <mask>255.255.255.255</mask>
</interface> </primary>
} </address>
</ip>
device PE21 {
</Loopback>
<interface xmlns="http://tail-f.com/ned/cisco- </interface>
ios-xr"> <interface xmlns="http://tail-f.com/ned/cisco-ios-xr" tags="merge">
<Loopback> <Loopback>
<id>168</id> <name>{loopback-intf}</name>
<ipv4> <description tags="merge">Loopback{loopback-intf}</description>
<address> <ip>
<mask>255.255.255.255</mask> <address>
<ip>10.168.23.66</ip> <primary>
</address> <address>{ip-address}</address>
</ipv4> <mask>255.255.255.255</mask>
</primary>
</Loopback>
</address>
</interface> </ip>
} ...
Refer back to your informal service design and the structure of data as well as the recorded native device
configuration in XML format. Paste the XML configurations into the XML template and replace the
parameter values:
 /device – use variable to reference to a device
 /device/loopback-intf – use a variable to reference interface number of the loopback. Note that there is
no need to specify the entire path as the looback interface is contained within the parent device.
 /device/loopback-intf/ip-address – use a variable to reference the IP address of the loopback. Note that
there is no need to specify the entire path as the IP address is contained within the parent loopback
interface.
 /device/loopback-intf/mask – use a static value for the subnet mask as it is required by the design to
always have a /32 subnet.

Template Options
The template uses tags to control the processing of lists:
 merge (default): the changes will be merged with the existing data
 replace: configuration will be replaced by the new configuration
 delete: delete anything from this point
 nocreate: merge data if it already exists, otherwise do nothing
You may also notice that the XML elements contain tags which control how NSO will process the elements:
 merge (default): the changes will be merged with the existing data; if the data structure does not exist it
will be created.
 replace: the configuration data will be replaced by the new configuration.
 delete: the configuration data will be deleted.
 nocreate: the configuration data will be merge only if it already exists, otherwise it will be ignored.
By default, the skeleton XML file will use the merge tag.
YANG Service Model
This topic describes the creation of a YANG service model.

a sample service

(XML)
(YANG) 4.
(XML) (YANG)

(YANG)
Finally we get to the configuration of the service model that will represent a vendor independent view of the
service to the operator either directly through the NSO CLI or GUI or through a separate frontend
management systems that is integrated with Cisco NSO (e.g. via Representation State Transfer [REST]
application programming interface [API]).

Creating the Service Model Example
 Step 1: Create service skeleton
 Step 2: Start translating the informal service model to a formal YANG
model
 Step 3: Create detailed YANG model for each service component
 Step 4: Finalize service model
The following example that is described on the following pages can be divided into the following four steps:
1. Create a service skeleton using the ncs-make-package command.
2. A visual or textual representation of the service and its parameters can now be translated into a high
level YANG model.
3. Each component is then described in detail (e.g. data types, restrictions (e.g. pattern, minimum or
maximum number of instances, range), annotation, etc.
4. A finalized YANG model is ready to be tested.
Step 1: Creating the Service Model: Start with Skeleton Model
module loopback {
namespace "http://com/example/loopback";  Change directory to
prefix loopback;
../src/yang
import ietf-inet-types { prefix inet; }
import tailf-ncs { prefix ncs; }
 Edit the skeleton service
augment /ncs:services {
list loopback { model
bname;
uses ncs:service-data;  The module augments the
ncs:servicepoint "loopback"; Cisco NSO services module
leaf name {
}
type string;  Devices are already
references
// may replace this with other ways of refering to the devices.
leaf-list device {
type leafref {  Replace the dummy leaf with
path "/ncs:devices/ncs:device/ncs:name";
} your service model
}
// replace with your own stuff here
leaf dummy {
type inet:ipv4-address;
Replace this section with
}
} your service model.
}
}
Change the directory to ../src/yang and edit the skeleton YANG file. The dummy leaf is there as a single
parameter of the service. This part can be deleted and replaced with your own service model. The rest of the
module file should be fine although you can change it if the service design requires it.

Step 2: Creating the Service Model: Informal Service Model
C devices
 Reuse existing resources
L devices (e.g. devices)
K name
 Augment the services
PE21
PE31
module
PE32
C services
L loopback
K servicename U loopback-intf U ip-address R device
OSPF Loopback PE21 1101 10.101.1.21 PE21

The figure illustrates the relevant portions of the NSO data model that are of interest to us when creating the
service model:
 The devices modules contains the information about the active devices in the environment.
 The service module contains the services and by using the augment /ncs:services option we will add our
own service to this module.
The section within the highlighted box is our addition to the services module:
 Each instance of the deployed service is uniquely identified using a name (sting). That means we will
use the list YANG keyword to allow multiple instances. The servicename leaf will be used as the key.
 Additionally, we want to ensure that the model does not allow the usage of incompatible configurations:
— Ensure global uniqueness of the IP address: unique ip-address
— Ensure local (per-device) uniqueness of the interface number: unique "device loopback-intf"
Step 2: Creating the Service Model: Top Level List
L loopback

module loopback {
namespace "http://com/example/loopback"; Add your data model to the skeleton based on
prefix loopback; the informal design you have created earlier:
import ietf-inet-types { prefix inet; }
import tailf-ncs { prefix ncs; }  Leaf servicename is used as key for the list
import tailf-common { prefix tailf; }
augment /ncs:services {  Leafs device, loopback-interface and ip-
list loopback {
leaf servicename { ... } address are leafs identifying the loopback
leaf device { ... }
leaf loopback-intf { ... } interface parameters
leaf ip-address { ... }
}
}
}
From the informal service model we see that we need four leafs in the loopback list:
 servicename: Unique key identifying the service instance.
 device: Reference to the active devices.
 loopback-intf: Loopback interface number.
 ip-address: IP address of the loopback interface.

Step 3: Creating the Service Model: Service Instance ID
L loopback

...
list loopback {  Tell NSO that this is a service
key servicename;
 The custom name for the service is used
uses ncs:service-data;
ncs:servicepoint "loopback"; as unique identifier in the list
leaf servicename {
tailf:info "Service Instance Name";  Optionally use the NSO-specific
type string;
}
annotations to provide textual description
... used in NSO CLI and GUI
The first parameter in our service is optional but it is good practice to allow any service instance to have a
descriptive name to make it easier for operators to find those instances. We could also create a descriptive
name by automatically combining multiple values into the name (e.g. customer name, device name, interface,
etc.).
Make sure you do keep the lines generated by the ncs-make-package command:
 uses ncs:service-data
 ncs:servicepoint "loopback"
The first line expands to a YANG structure that is shared amongst all services. The second line connects the
service to the Java callback.
You are also encouraged to use the NSO-specific annotations to provide additional information for the
service model by first importing the tailf-common module. In the example we use the tailf:info annotation
which provides a description of the parameter when accessed via the NSO CLI or GUI. Use the man
tailf_yang_extensions command on the server to get a list of all annotations and their descriptions.
Step 3: Creating the Service Model: Implement Service Model
L loopback

...
list loopback {  Keep the default reference to the live
...
leaf device {
list of devices
tailf:info "Router name";
mandatory true;  Optionally, you may limit the
type leafref {
path "/ncs:devices/ncs:device/ncs:name"; referenced devices (e.g. only PE
}
} devices
...
The second parameter is the device on which we want to configure a loopback interface. In this example we
leave the default reference as generated by the ncs-make-package command. We only added the description
to the option.

Step 3: Creating the Service Model: Implement Service Model (Cont.)
L loopback

...
list loopback {  One explicit design
... requirement: loopback
leaf loopback-intf {
tailf:info "Loopback Interface Number from 1100 to 1199"; interface number must be
mandatory true;
type uint32 { between 1100 and 1199
range "1100..1199";
}
}
 One implicit requirement:
... loopback interface number
is mandatory
The third parameter is the loopback interface number. We use the integer data type (uint32 in the example)
and we further limit the data type to only accept the number range set forth in our design – from 1100 to
1199.
Step 3: Creating the Service Model: Implement Service Model (Cont.)
L loopback

...
list loopback {  The inet:ipv4-address data
... type limits the value to a
leaf ip-address {
tailf:info "Valid IP range from 10.100.x.x to 10.199.x.x."; properly formatted IPv4
mandatory true;
type inet:ipv4-address { address
pattern "10\.1[0-9][0-9]\.[0-9]+\.[0-9]+";
}
}
 A additional pattern is used
... to further limit the address
to the desired range
The last parameter is the IP address of the loopback interface. A number of data types are available to
support common scenarios by importing the two modules defined by RFC-6991 Common YANG Data
Types:
 ietf-inet-types
 ietf-yang-types
In this case we make use of complex network data types provided by ietf-inet-types where we can enforce
the proper IP version 4 (IPv4) address format. In addition, we limit the IP address to the required range of
addresses as shown by the sample using the pattern command.

Regular Expressions – Quick Overview
Matching a single character
. dot matches any single character
[a-zA-Z0-9] matches a single character from a range of characters
Quantifiers
char* The preceeding character appears zero or more times
char+ The preceeding character appears one or more times
char? The preceeding character appears zero or one time
char{n} The preceeding character appears exactly n times
char{n,} The preceeding character appears at least n times
char{n,m} The preceeding character appears at least n and no more than m times
Grouping
(abc)* The preceeding group of characters appears zero or more times
Logical operators
(abc)|(cde) Matches at least one of the expressions on left or right of the OR operator
[^a-zA-Z0-9] Matches a single character NOT from the specified range of characters
Escape character to match any character that has a special meaning in regular expressions: .?+*(){}[]\|
\. Matches the dot character
\\ Matches the backslash
Multiple character escape sequences: \w \W \s \S \d \D
\d Matches any decimal number; equals [0-9]+
\w Matches a contiguous sequence of alphanumeric characters; equals [a-zA-Z]+
At this time it may be beneficial to revisit the most common regular expression options that can be used with
YANG. The regular expression rules used are defined in XML Schema Part 2: Datatypes Second Edition
(http://www.w3.org/TR/2004/REC-xmlschema-2-20041028/#regexs).
 XML Schema Part 2: Datatypes Second Edition defines regex rules

 Regular expressions search for substrings within a string
 In Cisco NSO regular expressions always match the entire string (i.e. ^ and $ are not required)
Regular Expressions - Example
Goal: match valid IP addresses in the range from 10.100.0.0 to 10.199.255.255  = match
valid not in range not valid IP not valid IP
10.100.1.1 10.200.1.1 1001.100.1.1 10.100.1.500  = no match
Which of the above addresses will be matched by the following regular expressions
10.\d+.\d+.\d+ 10.100.1.1  10.200.1.1  1001.100.1.1  10.100.1.500 
10\.\d+\.\d+\.\d+ 10.100.1.1  10.200.1.1
 1001.100.1.1
 10.100.1.500

10\.1[0-9][0-9]\.[0-9]+\.[0-9]+ 10.100.1.1  10.200.1.1  1001.100.1.1  10.100.1.500

Do not reinvent the wheel - reuse ietf-yang-types and ietf-inet-types modules where a
number of useful data types are already defined
(([0-9]|[1-9][0-9]|1[0-9][0-9]|2[0-4][0-9]|25[0-5])\.){3}([0-9]|[1-9][0-9]|1[0-9][0-9]|2[0-4][0-9]|25[0-5])
ipv4-address
data type
and
10\.1[0-9][0-9]\.[0-9]+\.[0-9]+ 10.100.1.1  10.200.1.1  1001.100.1.1  10.100.1.500 
The above figure provides an example for practicing regular expressions ant to illustrate that a simplified
regular expression may not provide adequate protection against invalid parameters being used.
The example at the bottom of the page illustrates the optimal approach where the complex regular
expressions can be used by importing modules that contain them and then simply augmenting them with
additional restrictions.
In the example we use the ietf-inet-types module which contains a very specific and accurate regular
expression to validate proper IPv4 address format and then augment it with our additional restriction.

Step 4: Creating the Service Model: Final Service Model
module loopback { leaf device {
namespace "http://com/example/loopback"; tailf:info "Router name";
mandatory true;
prefix loopback; type leafref {
import ietf-inet-types { prefix inet; } }
import tailf-ncs { prefix ncs; } }
import tailf-common { prefix tailf; } leaf loopback-interface {
tailf:info "Loopback Interface Number from 1100 to 1199";
augment /ncs:services { mandatory true;
type uint32 {
list loopback { range "1100..1199";
}
key servicename; }
unique "device loopback-intf";
unique "ip-address"; leaf ip-address {
tailf:info "Valid IP address range from 10.100.x.x to 10.199.x.x.";
uses ncs:service-data; mandatory true;
ncs:servicepoint "loopback"; type inet:ipv4-address {
pattern "10\.1[0-9][0-9]\.[0-9]+\.[0-9]+";
leaf servicename { }
tailf:info "Service Instance Name"; }
type string; }
} }
... }
 Parameter hierarchy, data types, restrictions, NSO-specific annotations (e.g.

descriptions used by the Cisco NSO GUI and CLI)
The printout above shows the entire service model that we have created to provision loopback interfaces on
routers.
Note that if you need to provide support for an additional type of device you do not have to change anything
in the service model. You simply need to add another mapping into the XML template.
Deploy a Service
This topic describes how to install a new service package and deploy service instances.

a sample service

(XML)
(YANG)

(XML) (YANG)
Compile & Deploy the

5. Service
The last step in the process is to enable the new service package.

Compile and Deploy the Service Model
cisco@nso:~/ncs-run/packages/loopback/src/yang$ cd ..
cisco@nso:~/ncs-run/packages/loopback/src$ make
/home/cisco/ncs-3.2.1/bin/ncsc `ls loopback-ann.yang > /dev/null 2>&1 && echo "-a loopback-ann.yang"` \
-c -o ../load-dir/loopback.fxs yang/loopback.yang
cisco@nso:/opt/ncs/ncs-3.2/packages/loopback/src$
admin@nso# packages reload
>>> System upgrade is starting.

>>> Sessions in configure mode must exit to operational mode.
>>> No configuration changes can be performed until upgrade has completed.
>>> System upgrade has completed successfully.
 Compile the changes on the server

 Request the reload of packages in the Cisco NSO CLI
In the shell, change to a parent directory where there is Makefile that was generated by ncs-make-package
command. Use the make command to compile the package. If the compile process fails you should see the
line number of the most probable origin of a mistake in either the YANG or XML file. Once you fix all
problems, the make process should complete successfully (i.e. no error message is displayed).
In the NSO CLI, issue the request packages reload command in the operational mode to tell the NSO server
to reload all packages including the new and changed packages. Note that this process may take a while.
Also note that there may be a misconfiguration in the package that did not cause the compilation to fail but
may fail the package validity check which will be reported by the NSO CLI.
You may also inspect the /var/log/ncs/ncs.log file to see the process of loading files and to see if any files
failed to load.
Parameter Restrictions Enforced Already in GUI and CLI
YANG data types and
constraints are validated
admin@nso(config)# services loopback Test device PE31 loopback-intf 123
------------------------------------------------------------------------^
syntax error: "123" is out of range.
admin@nso(config)# services loopback Test device PE31 loopback-intf 1123 ip-address 10.123.1.1
admin@ncs(config-loopback-Test)# top
Commit complete.
admin@nso(config)# exit
admin@nso# show service loopback Test
services loopback Test
device-modifications devices {
device PE31 {
config {
ios:interface {
+ Loopback 1123 {
+ description Loopback1123;
...
 First configuration validation stage

Once the new service package is successfully loaded you can try to configure a loopback interface, except
this time you will use the set service command instead of the set device command. As you can see from the
example, the set service command is vendor independent where we only set the service's parameters without
concerning ourselves with the actual syntax of native CLI's of all the used device types. You may, however,
still use the commit dry-run outformat native command to see the device-type-specific commands that will
be deployed to the target devices.

Summary
 Service design goal is simplicity for the operator :
 Minimum set of parameters for the service (optimization)
 Strict enforcement of parameters to minimize human error (standardization)
 Thorough testing of service configuration and all possible service options to ensure
robustness of the solution
 NSO and YANG provide modularity and flexibility for service designers
References
 Cisco documentation.
Lesson 3-2
FASTMAP
Overview
This lesson explains what the FASTMAP algorithm is, what it does and how it streamlines the
whole service lifecycle.
Objectives
 Explain what FASTMAP algorithm does
 Describe how FASTMAP covers the whole service lifecycle
 Point out FASTMAP usage considerations
 Explain which mechanisms available to complement FASTMAP
Introduction
This topic explains what FASTMAP is.
Overview Create
Delete
 NSO reduces service to Modify
device configuration UI/API Transactions
mapping to minimum
Service YANG Service
 Covers complete service Models
Configuration
lifecycle Create
Delete
 Minimum configuration Modify
change is calculated and Device YANG Device
applied automatically Configuration Models
CLI
SMP Commands
NETCONF
Device
Commands
Cisco Network Services Orchestrator reduces the mapping challenge to a bare minimum. The solution covers
the complete service life-cycle so that services can be changed and deleted and NSO will automatically
calculate the minimum change to be applied to the network.
How does NSO solve this? Service and device models are the foundation for the solution. NSO uses the
IETF standardized YANG [RFC 6020] modeling language to specify service models as well as device
models. This is true even for devices that do not support YANG natively like CLI or Simple Network
Management Protocol (SNMP) based devices. The NSO tool-chain automatically generates YANG from
SNMP MIBs and for CLI devices the declarative YANG model can automatically render the corresponding
CLI commands. This collapses the first problem; the mapping is reduced to a YANG to YANG mapping
problem rather than the normal mapping from informal service models to sequences of CLI commands or
sequences of SNMP SETs.
How can NSO calculate the minimum diff towards the network? NSO stores the service instances and the
device configurations in the embedded Configuration Database (CDB). In contrast to traditional "offline"
inventory systems NSO focus on transactional integrity between the data-store and the network. The core
technology of NSO is the capability to read and write configuration to/from the devices. This leads to a "real-
time" database that is always in sync with the network. Therefore NSO can look at the desired device
configuration and generate the diff versus current configuration at the model-level. Second, NSO can
automatically render the underlying device commands for various interfaces like Cisco-style CLI, Network
Configuration Protocol (NETCONF), SNMP etc. No programming is required for this. Note that this also
includes tricky problems like sending CLI commands or SNMP protocol data units (PDUs) in the correct
order, depending on what has changed.
How is the transformation from service models to device models defined? This is normally a complex
problem. It might look easy from a 1000 feet view, but when it comes to the actual configuration values for a
router there are configuration details that need to be well defined. NSO simplifies this drastically by use of
the FASTMAP algorithm. Typically, an engineer defines a higher level service model representing for
example the VPN service itself and this service shall result in actual device configurations.
FASTMAP
 Patented algorithm that records the modifications in the service creation

 Reduces the complexity of change and deletion of a service
 Service and device models are rendered in real-time
 Any kind of service modification will automatically calculate the minimum diff to the network.
 Deleting a service will automatically clean up data on devices.
FASTMAP is the patented algorithm that records the modifications in the create() callback, and is
responsible for automatically handling the modify and delete case.
FASTMAP enables automatic management of any kind of change and deletion of a service. All change
scenarios and deletion are inferred from a single definition of the creation of the service. The mapping from
the service create to the corresponding device configuration is defined in a high level application
programming interface (API) or through a template. The programmer only has to define the service create
method. If later on a user changes or deletes an existing service NSO calculates the changes.
As a result, at any point in time a user or external client can modify a service and NSO will automatically
calculate the required minimum diff to the network. Also deleting a service from the network will
automatically clean up all configuration data on the devices.

FASTMAP (Cont.)
 Service dry-run:
 Displays the calculated minimum diff
 Does not execute the transaction
 Service check-sync:
 Is the service configuration in sync with the actual device configuration?
 Detects manual configuration changes.
 Shows the minimum diff to restore the service.
 Service re-deploy:
 Generates the minimum diff and restore a service to the network
On top of this FASTMAP automatically enables the following functions:

1. Service dry-run: if I apply this service to the network, what will happen? The output can be shown in a
data-model general way as well as a native CLI, NETCONF, etc. output.
2. Service check-sync: is the service configuration in sync with the actual device configuration? This can
detect the case that a network engineer has modified the device configuration by using the native CLI
and that the change is in conflict with a desired service configuration. It can also show the minimum diff
to restore the service.
3. Service re-deploy: generate the minimum diff to restore a service and make it happen in the network.
Service and Device Models
This topic explains what service and device models are.
Service Models
 A Service has a different meaning to different people

 Network Services, Hosting Services, Triple play, Quad play, …
 A Service has to do with our business – what are we delivering?

 A Service Model is a black-box definition how the service is configured:
 What are the input parameters that define the service?
 Example of a Firewall Network Service:
Source IP
Source port Firewall Service

Model
Protocol
Services, service models, and device models are vague terms and can mean different things for different
people. A Service Model is a black-box definition how the service is configured. What are the parameters
that are entered by a network engineer in the NSO CLI/WebUI? What are the parameters that are sent to
NSO from the order management system to provision the service?

Device Model
 Refers to an actual device type (e.g. Cisco IOS router)

 It is normally a part of the NED
 Devices that support NETCONF/YANG provide their own models
 Specify configurable parameters on the device
Device models in NSO normally refer to concrete models of the actual device type. It is connected to the
underlying device interface and network element drivers (NED). Of course, if the device supports
NETCONF/YANG the device model is the actual YANG model from the device vendor. For SNMP, it is the
YANG model generated by the NSO tool-chain from the MIBs. For CLI devices like for example a Cisco
IOS device it is the YANG model that is part of the CLI NED.
So device models are concrete, they specify the relevant parameters that can be configured on the device.
This is not to be confused with abstract general device models that do not map to an actual device. So in the
context of service mapping, the service model shall be mapped to a concrete exact model of the devices that
are included in the solution. NSO allows for an abstraction mechanism to provide an abstracted view of
different device vendors.
So, in theory, the service model could be mapped to abstractions, which in turn map to the actual concrete
device models. Experience has shown that it is better to let the service models be the "abstraction" and map
that to concrete device models rather than to provide a vendor abstraction layer. In NSO context, the service
models are the abstraction.
FASTMAP Principles
This topic describes the FASTMAP functionality.
FASTMAP
 Simplifies service management actions:

 Create: service model focuses on the "to-be" state of configuration
 Modify: FASTMAP optimizes the process of modification of configuration
 Delete: FASTMAP optimizes the process of deletion of configuration
 Service designer only focuses to the "to-be" state, no need to dwell on
modify and delete operations
FASTMAP was primarily designed to simplify service management actions:

 Create: service model focuses on the "to-be" state of configuration
 Modify: FASTMAP optimizes the process of modification of configuration
 Delete: FASTMAP optimizes the process of deletion of configuration
Service designer only focuses to the "to-be" state, no need to dwell on modify and delete operations.

FASTMAP Example: P2P L2 MPLS VPN
remote=10.1.1.15 remote=10.1.1.11
intf=0/5 pw-id=102 intf=0/9
device=PE11 device=PE12
 Each side of the point-to-point L2 VPN is defined by the following

configuration parameters:
 Common pseudowire identifier (pw-id)
 Device identifier (device)
 GigabitEthernet interface identifier (intf)
 Remote IP address for directed LDP (remote)
The figure illustrates a sample service that will be used over the following pages to explain the behavior of
FASTMAP when creating, modifying and deleting service instances.
A simple Point-to-Point Layer-2 MPLS VPN is used. Each side of the point-to-point L2 VPN is defined by
the following configuration parameters:
 Common pseudowire identifier (pw-id)
 Device identifier (device)
 GigabitEthernet interface identifier (intf)
 Remote IP address for directed LDP (remote)
FASTMAP: Create a Service Instance
Undo
NSO stores the device level undo
Service
Model Service Instance information (reverse-diff) for each
service instance as a binary
Database APIs object inside the service instance
Create
Model-to-model
mapping
Database APIs
 Create
 Modify
Device
Models Device Changes  Delete
To
devices
The figure illustrates the create method in NSO:

1. A newly-created service instance is mapped to the configuration of the devices involved in this service
instance.
2. The configurations are sent to the devices using whatever communication method was selected for the
device (e.g. NETCONF, CLI). This process is regarded as a single transaction which means that every
configuration atom must be successfully applied in order for the transaction to succeed.
3. A reverse diff is stored in the configuration database in order to support a possible future deletion of the
service instance.

Example: Create a New Service Instance
admin@nso# config
Entering configuration mode terminal  YANG service model governs
admin@ncs(config)# services l2vpn ACME service parameter API
admin@ncs(config-l2vpn-ACME)# pw-id 102
admin@ncs(config-l2vpn-ACME)# link Site1
admin@ncs(config-link-PE11)# device PE11
admin@ncs(config-link-PE11)# intf 0/5
admin@ncs(config-link-PE11)# remote 10.1.1.15
admin@ncs(config-link-PE11)# exit
admin@ncs(config-link-PE11)# device PE12
admin@ncs(config-link-PE11)# intf 0/9
admin@ncs(config-link-PE12)# remote 10.1.1.11
admin@ncs(config-link-PE12)# top
admin@ncs(config)#
The sample configuration illustrates the configuration of the P2P L2 MPLS VPN using the NSO CLI.
Example: Create a New Service
admin@ncs(config)# commit dry-run
device PE11  NED device model governs
config {
ios:interface { device configuration
GigabitEthernet 0/5 { parameters
xconnect {
+ address 10.1.1.15;
+ vcid 102;  XML, Java or Python map
+ encapsulation mpls;
} service parameters to device
}
} configurations
}
device PE12
config {
ios:interface {
GigabitEthernet 0/9 {
xconnect {
+ address 10.1.1.11;
+ vcid 102; Service parameters
} mapped to device
}
} configuration
When using the commit dry-run command, the curly-braces type configuration will be shown and the "+"
and "-" signs will indicated the changes that will be appliend in case a full commit is executed. When a new
service is created, the minimal diff for the device configuration is calculated automatically. The picture
above shows the result of this minimal diff by indicating the new configuration lines with a ‘+’ sign.

Example: Create a New Service (Cont.)
admin@ncs(config)# commit dry-run outformat native
device PE11
 CLI NED's YANG model also
interface GigabitEthernet0/5 contains additional information
xconnect 10.1.1.12 102 encapsulation mpls
exit
that governs mapping of YANG
exit statements to CLI commands
device PE12
interface GigabitEthernet0/9
exit
exit
admin@ncs(config)#
Can display native
commands in case
of CLI NED
Similarly, using the commit dry-run outformat native command, the device's native configuration will be
displayed in case we are using a CLI NED. CLI NED's YANG model contains additional information that
governs mapping of YANG statements to CLI commands. NETCONF capable devices would receive
configuration in the form of XML that can also be displayed using the commit dry-run outformat xml
command.
FASTMAP: Service Create
CDB / Device
/services /devices
./l2vpn[name='ACME'] ./device[name='PE11'] PE11

./config interface GigabitEthernet0/5
./pw-id=102 xconnect 10.1.1.15 102 encapsulation mpls
./interface !
1 2 ./link[2] ./GigabitE[name='0/5']
./device='PE11' ./xconnect
PE12
./interface='0/5' address='10.1.1.15'
./remote='10.1.1.15' vcid='102'
encapsulation='mpls' !
FASTMAP: service mapping & diff  Configuration sent to devices

& remember reverse diff
The figure illustrates the two major branches in the CDB governing services and devices:
 The /services subtree contains our service instance configurations
 The /devices subtree contains our device configurations
The template, Java or Python based mapping logic transforms service parameters into device configurations.
The minimal difference between the current state and the new state (diff) is then sent down to the devices.
When the service instance is created the reverse of the resulting device configuration (referse diff) is also
stored together with the service instance.

FASTMAP: Modify a Service Instance
Undo
Service Update the undo
Service Instance
Model information for the modified
Undo
Database APIs service instance
Create
Delete
Delete Create the
existing modified instance
instance
Database APIs
 Create
 Modify
Device
To
devices
Only send differences
to devices.
The figure illustrates the modify method in NSO which is really just a combination of delete and create:
1. Delete the current service instance (only within the Cisco Discovery Protocol, no actual device
configuration happens at this stage).
2. Create a new service instance using the modified parameters (only within the CDP; no actual device
configuration happens at this stage).
3. Compute the configuration changes between the previous and new state.
4. Send only the changes to the devices.
Modify and Existing Service: Example 1
admin@nso# config
Entering configuration mode terminal  Only one parameter changed
admin@ncs(config)# services l2vpn ACME
admin@ncs(config-link-PE12)# top  CDB shows only minimal diff
admin@ncs(config)# commit dry-run changes
device PE11
config {
ios:interface {
xconnect {
- vcid 102;
+ vcid 122;
}
}
}
}
device PE12
config {
ios:interface {
xconnect {
- vcid 102;
+ vcid 122;
}
The next example shows how the modify action is handled by FASTMAP. The figure illustrates the minimal
diff based on the changed pseudowire ID (called pw-id in the service model and vcid in the device model).
Looking at the data structure in the CDB we see that the existing VCID 102 will be removed and the new
VCID 122 will be added.

Modify and Existing Service: Example 1 (Cont.)
admin@nso# config
Entering configuration mode terminal
 Changed parameter affects
admin@ncs(config)# services l2vpn ACME both devices
admin@ncs(config-link-PE12)# top  CLI NED may have additional
device PE11 dependencies between
interface GigabitEthernet0/5 configuration options (e.g.
exit multiple parameters in a single
exit line)
device PE12
exit
exit
When using the commit dry-run outformat native command we see that more than just the VCID will be
changed. This is because we are using a CLI NED and the CLI syntax bundles multiple parameters into a
single command. Hence, we need to re-apply the entire xconnect command including the IP address even
thoug we did not change the IP address. These dependencies are also described in the device's YANG model
using the NSO-specific instructions that govern how YANG statements are translated into CLI commands
and vice versa.
FASTMAP: Service Modify (1)
CDB / Device
/services /devices

./interface !
PE12
./remote='10.1.1.15' vcid='122'
encapsulation='mpls' !
 Only diff sent to devices

FASTMAP: service mapping & diff  CLI NED may have additional dependencies
& update reverse diff between configuration options (e.g. single
© 2016 Cisco and/or its affiliates. All rights reserved. line) Cisco Network Services Orchestrator 21
The figure illustrates the tree structure and which nodes get changed in the VCID modification and how these
modifications translate into device CLI commands.

admin@nso# config
 Only one parameter changed
admin@ncs(config-l2vpn-ACME)# link Site1  CDB shows only minimal diff
admin@ncs(config-l2vpn-ACME)# remote 10.1.1.12 changes
device PE11
config {
ios:interface {
xconnect {
- address 10.1.1.15;
+ address 10.1.1.12;
}
}
}
}
The second modification example changes the IP address in our existing L2 MPLS VPN service instance.
This change only affect one device (PE11).
admin@nso# config
admin@ncs(config)# services l2vpn ACME only one device
admin@ncs(config-l2vpn-ACME)# remote 10.1.1.12  CLI NED may have additional
admin@ncs(config)# commit dry-run outformat native dependencies between
device PE11 configuration options (e.g.
xconnect 10.1.1.12 122 encapsulation mpls multiple parameters in a single
exit line)
exit
The change only affects one device but we still need to re-enter the entire xconnect command.

CDB / Device
/services /devices

./interface !
PE12
./remote='10.1.1.12' vcid='102'
encapsulation='mpls'
FASTMAP: service mapping & diff Diff sent only to affected device
& update reverse diff
The figure illustrates the tree structure and which nodes get changed in the IP address modification and how
these modifications translate into device CLI commands.
admin@nso# config
admin@ncs(config-l2vpn-ACME)# intf 0/6  CDB shows only minimal diff
admin@ncs(config-link-PE12)# top changes
device PE11
config {
ios:interface {
xconnect {
- address 10.1.1.5;
- vcid 123;
- encapsulation mpls;
}
}
xconnect {
+ address 10.1.1.5;
+ vcid 123;
}
}
}
}
The third modification example illustrates the reconnecting of a customer site from interface
GigabitEthernet0/5 to GigabitEthernet0/6.

admin@nso# config
admin@ncs(config)# services l2vpn ACME only one device
admin@ncs(config-l2vpn-ACME)# intf 0/6  CLI NED may have additional
admin@ncs(config)# commit dry-run outformat native dependencies between
device PE11 configuration options (e.g.
no xconnect 10.1.1.12 122 encapsulation mpls multiple parameters in a single
exit line)
exit
exit
The example illustrates how the reverse diff will make sure that the existing configuration is removed and the
new mapped configuration will be applied.
CDB / Device
/services /devices

./pw-id=102 no xconnect 10.1.1.12 102 encapsulation mpls
./interface !
1 2 ./link[2] interface GigabitEthernet0/6
./GigabitE[name='0/6']
./xconnect !
./device='PE11'
./remote='10.1.1.12' vcid='102' PE12
encapsulation='mpls'
FASTMAP: service mapping & diff Diff of parent requires

& update reverse diff reconfiguration of all child nodes
The figure illustrates the tree structure and which nodes get changed in the interface modification and how
these modifications translate into device CLI commands.

FASTMAP: Delete a Service Instance
Undo
Service
Service Instance
Model
Undo Database APIs
Delete
Apply the undo
configuration
Database APIs
 Create
 Modify
Device
To
devices
The figure illustrates the delete method in NSO:

1. The stored undo information (i.e. reverse diff from the create method) is sent to the devices to change
the state of configuration atom to that before the create method.
Delete a Service Instance
admin@nso# config
admin@ncs(config)# no services l2vpn ACME
device PE11  CDB shows only minimal diff
config {
ios:interface { changes
xconnect {
- address 10.1.1.12;
- vcid 122;
}
}
}
}
device PE11
config {
ios:interface {
xconnect {
- address 10.1.1.11;
- vcid 122;
}
}
}
The last example illustrates the delete action where the NSO will apply the reverse diff to revert back to the
original state before this service instance was created.

Delete a Service Instance (Cont.)
admin@nso# config
 Reverse diff used to undo the
admin@ncs(config)# services l2vpn ACME configuration changes of the
admin@ncs(config-l2vpn-ACME)# intf 0/6
service instance
device PE11
no xconnect 10.1.1.12 122 encapsulation mpls
exit
device PE12
exit
exit
The example illustrates the native version of the reverse diff.
FASTMAP: Service Delete
CDB / Device
/services /devices
./device[name='PE11'] PE11
./interface !
./GigabitE[name='0/6']
PE12
!
FASTMAP: reverse diff applied Reverse diff sent to devices

Once the reverse diff is applied, the service instance is no longer present in the services subtree and the
devices subtree reflects the device configurations without the unconfigured service.

Advanced FASTMAP
This topic discusses some of the advanced features of FASTMAP.
Advanced FASTMAP
 Shared service resources - multiple service instances configure the

same shared prerequisite configuration
 Example:
 P2P L2 MPLS VPN service requires Loopback interfaces to implement
directed LDP
 One implementation options could be to put prerequisite configuration into
service implementation
One of the advanced features of FASTMAP is that it keeps track of each configuration element's owner (i.e.
creator) thus enabling the configuration of shared service resources without worrying about what service
instance deletions will do to other service instances relying on the same shared configuration.
Services Sharing Resources
CDB NSO maps service parameter
Service Instances Device Changes to device configuration
L2 VPN a1 xconnect a1
Refcount=1 NSO counts owners of each
Backpointer=l2vpn[name='A1'] configuration element
loopback 1
Operator creates Refcount=1 NSO remembers owners of
service instance Backpointer=l2vpn[name='A1']
each configuration element
The figure illustrates how the deployment of first L2 MPLS VPN service instance on a given device also
creates the prerequisite with is a Loopback interface to enable the configuration ant establishment of directed
LDP sessions. As you can see, the service parameters will result in two elements being configured on the
analyzed device: xconnect and loopback.
NSO keeps track of configuration element owners using the so-called backpointers and also counts the
number of owners using the so-called refcounter.

CDB
Service Instances Device Changes
L2 VPN a1 xconnect a1
Refcount=1
Backpointer=l2vpn[name='A1']
Backpointer=l2vpn[name='a1']
L2 VPN a2
xconnect a2
Refcount=1
Backpointer=l2vpn[name='a2'] NSO increases the count of
owners of shared
Operator creates loopback 1 configuration elements
another service
Refcount=2
instance Backpointer= l2vpn[name='a1'], NSO updates the list of
l2vpn[name='a2'] owners of shared
configuration elements
When adding a second service instance to the same device we no longer need to configure the loopback
address but NSO should remember that there are now two owners (services that depend on the loopback
configuration) and so the FASTMAP algorithm will increase the refcounter to 2 and add the second instance
to the backpointer list.
CDB
Service Instances Device Changes NSO only deletes those
xconnect a1
elements whose reference
L2 VPN a1
count is 1
Refcount=1
Backpointer=l2vpn[name='A1']
Backpointer=l2vpn[name='a1']
L2 VPN a2
xconnect a2
Refcount=1
Backpointer=l2vpn[name='a2'] NSO decrements reference
count on those elements that
Operator deletes were not deleted
one service loopback 1
instance Refcount=1 NSO updates the list of
Backpointer= l2vpn[name='a2']
owners of shared
configuration elements
The third example illustrates the decommissioning of the first service instance. This results in the application
of reverse diff but only for those configuration elements whose refcounter equals 1. The loopback
configuration will only have its refcounter decremented and the first service instance removed from the
backpointer list.

CDB
Service Instances Device Changes NSO only deletes those
elements whose reference
count is 1
L2 VPN a2
xconnect a2
Refcount=1
Backpointer=l2vpn[name='a2'] NSO deletes shared element
Operator deletes as well
last service loopback 1
instance Refcount=1
Backpointer= l2vpn[name='a2']
The last example illustrates the decommissioning of the last service instance thus also removind the loopback
configuration due to refcounter now reaching 0.
Advanced FASTMAP
 There are other service implementation options where specifics of

FASTMAP must be understood and addressed:
 Using Java or Python for advanced service mapping logic
 Using Reactive FASTMAP to handle multiple stages in the configuration of
devices
The previously explained functionality is for reference only when template-based service mapping is used. It
is, however, important to understand FASTMAP when using other service mapping options such as Java or
Python callbacks (not covered in this course).

Reactive FASTMAP
Example: Virtual Network Function (VNF) Solution
Service Order Request
1. Service Request arrives 1
2. Service instance is created, but it 5
requires VM resources first Service Model
3. Device Manager first contacts the

VM Manager, which spins up VMs 2 4
4. Once VM is ready, a service trigger Device Model
application invokes service

application again
6 6 6
3
5. Service redeploy is issued
6. Now devices can be configured
VNF Infrastructure VM Manager
The figure illustrates the two-stage service deployment using Reactive FASTMAP where we must first
instantiate VNFs (stage 1) before being able to configure them (stage 2).
1. A service order comes in from operator or operations support system (OSS).
2. Service application reads service instance data and configures network elements accordingly. If new
VMs (or other environment setup) are required before the actual network devices can be reached, the
service application configures the Cloud Manager to have additional virtual machines (VMs).
3. NSO Device Manager sends the first incarnation of this transaction to the network, requesting the Cloud
manager to spin up new VM(s).
4. A service trigger application is listening for VM change events and is notified when the new VM is
ready. The service trigger application starts a new NSO transaction, configures the new device VMs in
the NSO device list and commits.
5. The service trigger application issues a service redeploy on the service(s) that are pending the VM
creation. This will invoke the service application again, like in step 2.
6. Only this time the all the necessary resources are available, and the service application will configure
them with the appropriate configuration. The NSO Device Manager sends out the second incarnation of
this transaction to the network.
Reactive FASTMAP (Cont.)
 Is a service activation pattern

 Used where service activation requires two or more stages
 Also used where service need to adapt to changes in environment
 Example: VMs are rehosted between Data Centers and underlying network
needs to adapt.
 The reactiveFASTMAP approach is typically required for more complex
services
The Reactive FASTMAP design pattern can be applied in use cases where services need to be activated in
two or more stages. This pattern is also applicable in use cases where the service needs to adapt to a changing
environment. If for example the Cloud Manager decides to move a VM from one host to another, the service
trigger application would notice and request the affected services to be redeployed. The service application
would then recompute the device configurations required to uphold the service in the new environment. NSO
Device Manager would then send out the net change to all affected devices, potentially even spinning up or
down VMs as necessary. If the service application is designed for this purpose, this adaptation may go on
throughout the entire life of the service.

Summary
 FASTMAP reduces the service to device transformation to a single create().
 NAVU API (Java, Python) gives programmatic access to service and device models.
 There is no code needed for service to device mapping.
 There is no code for persistence.
 Reactive FASTMAP can be used for complex services.
References
Lesson 3-3
Service Design
Overview
This lesson builds on the knowledge gained about YANG modeling language and the
capabilities of Network Services Orchestrator (NSO). This lesson will use a sample service
provider service (Layer-3 Multiprotocol Label Switching [MPLS] VPN) to illustrate the service
design process.
Objectives
 Learn to design and implement services using Cisco NSO and YANG
 Use the top-down design approach
 Use the bottom-up design approach
Service Design
This topic describes the classing network service design process and how this process may be
impacted or changed when including a YANG service design as part of the process.
Typical Service Design Process

 Service Description
Architect
 High Level Design
 Development, Testing and/ or PoC Lab
 Detailed Design
 Pilot Deployment
Engineer
 Final Deployment
 Service Operation
Operator
A typical design process in a service provider environment takes many stages. Given a certain business
environment and the generation of a service idea we will firs start by formulating the new service on a very
high level. Eventually, the network architects and engineers will start creating a high-level design which will
already detail the service parameters.
As the service design process progresses it is typically required to do a proof of concept (PoC) deployment in
a lab to ensure that the service is technically feasible. Finally, the detailed design is created which describes
the new service in enough technical detail so that it can be implemented and verified. The new service may
be deployed throughout the environment or it may initially be deployed in smaller scale (i.e. pilot
deployment). The final step in the process is releasing the new service and have the operations team take
over the provisioning of the service.
Augmented Service Design Process
 Service Idea
Top- Down Approach
 High Level Design
Design Service in NSO
 Development, Testing
and/ or PoC Lab Bottom- Up Approach
 Detailed Design
 Pilot Deployment
 Final Deployment
 Service Operation
Deploy Service in NSO
The stage when the services are being tested in the lab is ideal to provide the required information and
resources that help in the design of service models in Cisco NSO. This allows the design processes (service
and NSO) to run in parallel so that when the service is being deployed it will already be supported by Cisco
NSO and ready for operators to start using it.
Top-Down NSO Design Approach
When the NSO design is considered in the early stages of the service design process we can use the top-down
design approach for NSO as well. This allows the NSO designer to use the service architect's input to create a
service model first without concern for the actual device-specific technical detail at this stage.
Bottom-Up NSO Design Approach
Sometimes the management aspect may be considered only in a later stage of the design process when a
service idea has already been transformed into an exact technical solution (e.g. tested in a proof of concept
lab). Here we may be faced with an engineering input (i.e. device configuration) which describes the service
at a much lower level (it may not actually describe a service but provide device configuration and parameters
for the service). The NSO design may have to use a reverse approach to transform the technical
implementation back into a high level service model.

Augmented Service Design Process (Cont.)
 Use architects to help in the

Architect
creation of the service model
Design
 Use engineers to help in the
Service in
creation of the mapping logic
NSO
and testing of the service
Engineer  Use operators to help integrate
NSO with operations processes
Deploy
Service in  Provide the end result to
Operator NSO operators
When using Cisco NSO for service provisioning it is ideal to reuse the service design process and resources
to also create a service model for Cisco NSO during the design process:
 The network architect will provide the high-level description of the new service and the required
parameters that define the service and the deployed service instances.
 The network engineer will create the service implementation instructions as part of the design process
and also test the configuration in the development lab. The configurations and the lab can then be used
to also design the YANG service models and the mapping logic.
 When it comes to the service management platform it is important to consider the requirements and
limitations of the operation's processes and procedures, their other operations support system /network
management system (OSS/NMS) tools and how NSO needs to interact with them. The operator's input
is required in the design process in order to ensure that the final solution fits best into the existing
operations environment.
 By the time the service has been designed and implemented in the environment to supports the new
services, the service model will be ready to be used by the operations team on daily basis for service
management.
Top- Down Approach
Architect Service Model (architect)
Design
Engineer Service in Device Specific Configuration in NSO
NSO
Operator Service Management Integration
In a top-down approach we are introducing the NSO into the service design process and can create a NSO
service model at an early stage in the design process. This model describes the service and makes it available
for testing at the operation level without having any actual underlying technical implementation (i.e.
devices). The engineering stage is involved later when the service model is being mapped to the actual
device configuration options.

Bottom- Up Approach
Device Configuration (engineer)
Device Specific Configuration in NSO

Design
Engineer Service in
NSO
Service Model
Operator Service Management Integration
When faced with a situation where a service design process is already at a stage where the network or
systems engineers are testing and implementing it in a lab environment (e.g. proof of concept lab) we must
adapt our NSO design process in order to be able to use NSO at the PoC stage. In this case we may decide to
use the engineer to provide the required input information. Engineer's input information will likely be very
technical such as topology information, device configurations, and configuration parameters (as opposed to
service parameters).
The network engineer responsible for designing and testing of the new service will provide the necessary
device configurations that are used to manually provision a new service. The NSO engineer can then
translate these commands into the Cisco NSO CLI. The XML output of the configuration can then be used to
design the service model and the mapping logic which will enable the new service to be provisioned in a
vendor independent fashion. Finally, the Cisco NSO server can be integrated with the existing management
portal used for service provisioning or even self-provisioning.
Sample Service: Layer- 3 MPLS VPN
CE- 13
Input resources:
Edge
NSO  Layer 3 MPLS VPN design
PE- 13
 Development lab
Core
CE- 11 PE- 11 P- 01 PE- 31 CE- 31
P- 03
Platforms at network edge:
CE- 32
 Cisco IOS routers
CE- 12 PE- 12 P- 02 PE- 32
L3 MPLS VPN
 Cisco IOS XR routers
 …
PE- 21
CE- 21
The figure illustrates a sample topology used in a lab environment to design and test a Layer-3 MPLS VPN
service. The environment uses a mixture of different device types from different vendors. Throughout this
lesson we will be creating this service and use Cisco IOS and Cisco IOS XR as examples of a mixed device-
type environment.
The specifics of the Layer-3 MPLS VPN service provisioning require us to focus only to the network edge -
provider edge (PE) devices and customer edge (CE) devices. In this lesson we will be focusing on the
configuration of this service on PE devices.

Top- Down Approach Bottom- Up Approach
Design steps: Design steps:

 Service model  Device configuration
 Device configuration  Mapping logic
 Mapping logic  Service model
Preferred approach Viable alternative when faced with

existing device configurations for a
service
The figure illustrates the two NSO design approaches. The preferred top-down approach would require the
NSO designer to be involved in the service design from the start and ensure that the service operations team
is included in the process. This allows for greater flexibility in the design process and early testing of the
management solution. The following section will describe this approach.
The alternative may be used when the NSO designer is involved in a design phase at a later stage or when,
for example, the engineer was charged with an additional task that required his technical solution to be
integrated with NSO.
Service Design for Cisco NSO
Top-Down Approach
This topic describes the top-down design approach which is the preferred approach and used
when the service design for NSO is considered at the early stages of the design process.

Top- Down Approach
 Define service characteristics
 Define service parameters
 Implement service model in YANG
A high-level service definition that includes service characteristics, limitations, parameters, etc. is the first
step in the top-down approach. An informal service model can be created without including any low-level
technical details at this stage. The first step can already result in a YANG service model that can also be
tested without the need for a length and complex physical lab setup.

Informal Service Design: Layer- 3 MPLS VPN
Routing Routing
Customer:
ACME Interface Interface
Site A Site X
Addressing Addressing
CE PE PE CE
VPN: Primary
Routing Routing
Interface Interface
Site B Site Y
Addressing Addressing
CE PE PE CE
 Service description: provide isolated any to any IP communication between customer sites
 Service parameters:
 Access interface: PE device and interface where the customer site is connected
 Addressing: IP address range and subnetting
 Routing: CE to PE routing protocol options: BGP, RIP, static
The figure illustrates our sample solution that will be used throughout this lesson – Layer-3 MPLS VPN.
The Layer-3 MPLS VPN service consists of a number of parameters that are needed in order to provision a
service instance. The parameters can be divided into three main groups:
 Access interface configuration where we may have a variety of interface types.
 Addressing of the access interface where we may use one or more numbering options (e.g. provider
assigned public or private addresses, customer assigned private addresses).
 Routing between the provider edge router and the customer edge router.
Note A typical Layer-3 MPLS VPN service would have many more characteristics such as any of a number of
quality of service mechanisms, other routing options, limits, filters, multicast, IP version 6 (IPv6), etc. This
example is condensed to fit the purposes of training.
Layer 3 MPLS VPN Service Model
Data path in l3mplsvpn: There can be many Each VPN instance can Each VPN instance
VPN instances of is assigned to a
 vpn-id have multiple links
the service (customer sites) customer
 vpn-name
 customer (reference) L l3mplsvpn
 link/
K vpn- id L vpn- name R customer
 link/interface
 link/routing-protocol L link
 link/device (reference) K link- id U linterface U routing- protocol R device
 link/static/ L static
 link/static/prefix
K prefix K mask
There are three options for
 link/static/mask routing: BGP, RIP or static
Static routing (if used) requires the
operator to assign prefixes
Based on the service characteristics and parameters we can create an informal design as illustrated in the
figure above. The figure illustrates YANG statements where, for example, a list statement ("L" in the figure)
is used for any object where we can have multiple instances (e.g. VPN instances, link instances within a VPN
instance, static routes for individual links within a VPN instance). Each list requires a key leaf ("K" in the
figure) which is used as identifier in the example above. The model also references NSO resources such as
customers (optional but recommended) and devices (required in order to be able to link the service to the
actual devices that will eventually be configured with the right commands).
The hierarchy of the informal model can also be represented in text (e.g. similar to directories) which will
help in referencing the data later on using XPath.
This informal design can now be "translated" into YANG.

Layer 3 MPLS VPN Service Model (Cont.)
module l3mplsvpn{
namespace "http://com/example/l3mplsvpn"; YANG statements representing our
prefix l3mplsvpn;
import ietf-inet-types { prefix inet; } informal design:
import tailf-common { prefix tailf; }  There can be many service instances
 Each instance can have one or more PE-
list l3mplsvpn {
leaf vpn-name { ... } CE links
leaf vpn-id { ... }
leaf customer { ... }  If static routing is chosen there may be
list link { one or more static routes
leaf site-name { ... }
leaf site-id { ... }
leaf device { ... }
leaf interface { ... }
leaf routing-protocol { ... }
list static {
leaf prefix { ... }
leaf mask { ... }
}
}
}
}
}
The informal design from the previous page has now been converted into YANG. The figure only illustrates
the main statements and the hierarchy of objects. The final detailed YANG service model will be covered in
the last section.
Top- Down Approach
 The NSO service model can be tested form the operator's
perspective even without any physical equipment
 Device configuration and mapping logic steps can also be performed
without any physical equipment:
 Use the netsim tool to emulate devices
 Enables faster development and testing
One of the main advantages of using the top-down approach is to be able to directly translate the need of the
service and the needs of operations into a testable solution without a heavy effort to build a physical proof of
concept environment.
A physical PoC can and usually will be used at a later stage at which time there will already be a functioning
service model that can be deployed. The NSO's netsim tool can be used until then to emulate the
environment and provide for flexibility and speed of development (e.g. frequent changes can be performed
efficiently if the design process so requires).

Bottom-Up Approach
This topic describes an alternative approach when the service design uses a highly technical
input from which we need to derive a service model.

Bottom- Up Approach
 The input data for a bottom- up design approach may be at a more
technical low level:
 Device types
 Device configurations
 Interface types
 Configuration dependencies and limitations
 Etc.
In the alternative approach we are interfacing with an engineer that can provide us with low-level
implementation characteristics. These characteristics may include information about device types, device-
specific configurations for all of the service configuration options (device specific), interface types,
configuration dependencies and limitations, etc.
The NSO designer must extract an informal service model from the information provided in the form of a
high-level design (HLD), low-level design (LLD), implementation plans, verification plans, etc.
The same sample Layer-3 MPLS VPN service will be used in this section to illustrate the technical detail that
may influence the design process.
Service Parameters: Access Interface
PE interface options:
Interface
 Physical interface: interface
CE PE
number
 802.1q VLAN:
802.1q  VLAN interface: VLAN
trunk
VLAN
or
CE PE  Subinterface: interface name, interface
number and VLAN
In the sample service we see that we may have two PE-CE connection options when looking at it from the
perspective of the PE device:
 A physical interface is used to terminate the connection from a customer site (e.g. Gigabit Ethernet
interface).
 A VLAN interface or a Subinterface to terminate a single VLAN coming in through a trunk interface
from an aggregating LAN switch.
Note There can be a number of other scenarios for connecting customer devices (e.g. virtual templates, tunnel
interfaces) and other interface-related characteristics such as service policies (quality of service [QoS]),
access lists, etc.

Service Parameters: IP Addressing
 PE- CE interface addressing:
 / 30 subnets from RFC 1918
.high IP prefix/30 .low IP address ranges:
CE PE
 10.50.0.0/16
 10.150.0.0/16
 10.250.0.0/16
 172.21.0.0/16
 172.31.0.0/16
 Point- to- point links with / 30 subnet

mask
In the sample Layer-3 MPLS VPN design, the service designer has chosen that the PE-CE links will use the
addresses provided by the service provider from the following range: 10.50.0.0/16, 10.150.0.0/16,
10.250.0.0/16, 172.21.0.0/16, and 172.31.0.0/16. The operator will chose the range that does not conflict
with customer's exiting address usage. All links will be point to point and will use a /30 subnet mask. The PE
router will be always used to lower IP address from the /30 subnet and the CE router will use the higher IP
address.
Service Parameters: Routing
PE- CE routing:
EBGP
BGP:
AS 65001
Peer address  Customer AS number: 65001 or customer
CE PE public AS number
RIPv2  Peer address
 Option: advertise default
CE PE RIP:
 Option: advertise default
Static routes
Prefix(es)
Static:
Next- hop address
CE  Prefix
PE
 Next-hop address
When choosing the routing option, the service provider will allow the customer to choose one of the three
available options:
 BGP: This option is the preferred and is used in more complex topologies (e.g. multi-homed customer
sites). The design also mandates that all customers in all sites will use the single private Border Gateway
Protocol (BGP) autonomous system (AS) number 65001 and that the peering will be established using
the directly-connected IP addresses on the PE-CE link.
 RIP: This option is used with customers that have equipment that does not support BGP.
 Static: This is a last resort option which requires the operator to manually enter the customer prefixes
for individual sites.

Informal Service Design: Service Configuration
Cisco IOS
vrf definition vpn10001 Parameter Value
rd 1:100 One instance
route-target both 1:10001 Service Instance ID 10001- 19999
!
address-family ipv4 RD and RT 1:<Service ID>
!
interface GigabitEthernet4 VRF name vpn<Service Instance ID>
description Connection to vpn10001 One or more instances
Interface Physical or VLAN interface
vrf forwarding vpn10001
ip address 172.31.1.1 255.255.255.252 Interface IP The lower IP in / 30 subnet
!
router bgp 1 Peer IP The higher IP in / 30 subnet
bgp log-neighbor-changes
address-family ipv4 vrf vpn10001 BGP routing option BGP Yes or No
redistribute connected Suboption: default
redistribute static origination BGP Remote AS 65001 for all sites and all VPNs
neighbor 172.31.1.2 remote-as 65001
neighbor 172.31.1.2 activate BGP Neighbor Equals peer IP
neighbor 172.31.1.2 default-originate BGP default origination Yes or No
neighbor 172.31.1.2 as-override
neighbor 172.31.1.2 allowas-in RIP Yes or No
!
router rip RIP routing option Static route Yes or No
address-family ipv4 vrf vpn10001 Suboption: default
network 0.0.0.0 Prefix any valid IPv4 prefix
default-information originate origination
no auto-summary Next- hop address Equals peer IP
!
ip route vrf vpn10001 192.168.11.0 255.255.255.0 172.31.1.2 Static routing option
The figure illustrates the Cisco IOS configuration provided by the network engineer. It contains all
configuration options needed to deploy a Layer-3 MPLS VPN service instance using manual configuration.
From the configuration we can determine the set of parameters and options that will guide us when designing
a service model.
Informal Service Design: Sample Service Configuration
Cisco IOS XR
vrf vpn10001
address-family ipv4 unicast
import route-target 1:10001 One instance
 The same set of parameters as with
!
export route-target 1:10001 Cisco IOS
interface GigabitEthernet0/0/0/1
vrf vpn10001 One or more instances
ipv4 address 172.31.1.5 255.255.255.252
!
router bgp 1 Cisco IOS XR (continued)
vrf vpn10001
rd 1:10001 router rip
address-family ipv4 unicast vrf vpn10001
redistribute connected interface GigabitEthernet0/0/0/1
redistribute static !
! BGP routing option RIP routing option
redistribute static
neighbor 172.31.1.6 Suboption: default origination redistribute connected Suboption: default origination
remote-as 65001 default-information originate
address-family ipv4 unicast !
route-policy pass in !
allowas-in 3
route-policy pass out router static
as-override vrf vpn10001
default-originate address-family ipv4 unicast
192.168.21.0/24 172.31.1.6 Static routing option
!
! !
! !
! !
This figure illustrates the Cisco IOS XR configuration for the same Layer-3 MPLS VPN service that is also
provided by the network engineer. The designer of the service model would request such configurations for
all device types that are used in the service provider's environment.
Note that in this particular case we have the same set of parameters that define a service instance for both
device types.

Informal Service Design: Service Parameter Optimization
Parameter Value YANG Statement YANG Data Type
Service Instance ID 10001- 19999 List
RD and RT 1:<Service ID> Leaf (created from service ID) custom string with pattern
VRF name vpn<Service Instance ID> Leaf (created from service ID) string
Interface List
Interface name Physical or VLAN interface Leaf (key) string
Interface IP The lower IP in /30 subnet Leaf (calculated, inventory) ipv4- address
Peer IP The higher IP in /30 subnet Leaf (calculated, inventory) ipv4- address
BGP Option Container
BGP Remote AS 65001 for all sites and all VPNs Leaf (static value can be used) as- number
BGP Neighbor Equals peer IP Leaf (equals Peer IP) ipv4- address
BGP default origination Option Leaf Boolean or Enumeration
Static route Option List
Prefix any valid IPv4 prefix Leaf (key) ipv4- address
Subnet mask any valid IPv4 subnet mask Leaf ipv4- address
Next- hop address Equals peer IP Leaf (equals Peer IP) ipv4- address
RIP Option Container
RIP default origination Option Leaf Boolean or Enumeration
Once we have collected all the configurations from the network engineer and have received the service
description from the service architect we can start creating a list of parameters that define a service instance.
The figure illustrates the parameters for our sample service. The indentation in the parameter column already
illustrates the hierarchy and interdependency of parameters:
 The service instance is described using a unique identifier from the defined range. The virtual routing
and forwarding (VRF) name, route distinguisher and route target are constructed from this identifier.
 Each instance can have one or more customer-facing interfaces (PE-CE interface). For each interface we
can set additional features:
— IP addressing
— Routing: BGP, Routing Information Protocol (RIP) or static routing
Now we can start translating this informal service model to a more formal YANG definition:
 YANG statements to describe the characteristics of parameters (e.g. leaf, list).
 YANG data type to control the value of parameters (e.g. string, integer, IP address).
The figure also illustrates the first approximation in determining the formal YANG constructs for our sample
Layer-3 MPLS VPN service. Most single parameters are constructed using the leaf statement. Those
collections of parameters that can have multiple instances, such as static routes, make use of the list
statement.
The next important step is to optimize the set of technical parameters in order to minimize the amount of
information that will be exposed to the operator of the service. The figure illustrates how we can reuse some
parameters to construct others, use formulas to calculate their values or simply use static values where
possible.
For example: the service ID is ideally suited to uniquely describe the service instance and be used to
automatically assign values to route distinguisher (RD), route target (RT) and VRF name.
Informal Service Design: Service Optimization Challenges
 Challenges:
 Inventory of IP subnets for PE- CE links
 Calculation of IP addresses from the subnet (local and peer)
 Inventory of customer- facing interfaces and VLANs
 Solutions:
 Option 1: Use Java to augment the template
 Option 2: Change rules to accommodate the template functionality
 Option 3: Use an external inventory system
When we are faced with the optimization of service parameters we may have a challenge of how to create
certain values automatically so that we do not unnecessarily burden the operator and also minimize the
chances of human error when service instances are being provisioned.
In the sample service we see that there is a need to assign IP addresses to the PE-CE interface. The question
is how we are going to keep track of the usage of IP addresses. One solution may be to augment the
template-based service model by adding a programmatic chunk that calculates the IP subnets and
corresponding link IP address for the purpose of configuring the IP addresses on the link and to use the
remote IP address for BGP peering configuration.
Alternatively, we may change the rules (i.e. simplify them) so that we can achieve a working solution
without needing to add a Java applet to do the more complex calculation. The third option is to let the
operator enter the IP address, which is suitable if the Cisco NSO is integrated with a frontend that is also
integrated with an existing inventory system.

Results of Service Parameter Optimization
Parameter Value YANG Statement YANG Data Type
Service Instance ID 10001- 19999 List uint32
Site ID 1- 200 Leaf uint32
Interface - List -
Interface name Physical or VLAN interface Leaf (key) string
BGP Option Container -
BGP default origination Option Leaf Boolean or Enumeration
Static route Option List -
Prefix any valid IPv4 prefix Leaf (key) ipv4- address
Subnet mask any valid IPv4 subnet mask Leaf ipv4- address
RIP Option Container -
RIP default origination Option Leaf Boolean or Enumeration
The table illustrates the result of our service parameter optimization process. A number of parameters are no
longer needed as they will be generated from other parameters.
Device Configuration
This topic describes how to create the mapping logic to translate the service model to device
specific configurations.
Create and Test the Service in the Development Lab

 Finalize service parameters with the architects and engineers

 Create mapping logic - perform manual deployment of a sample service
instance using the NSO CLI instead of the device CLI:
 In a lab environment
or
 Using the netsim tool (faster, easier, fewer resources required)
When we have acquired the device configurations and finalized the informal service design and created the
list of service parameters, we can proceed to convert these into the formal service design using YANG to
model the service and the XML mapping template.
The netsim tool can also help us in the next step where we create the mapping logic to map the service
parameters to device configurations.

Device Configuration Using Cisco NSO CLI
Cisco IOS Configuration
admin@ncs(config)# /* VRF Configuration */
admin@ncs(config)# devices device PE12 config ios:vrf definition vpn10001
admin@ncs(config-vrf)# rd 1:10001
admin@ncs(config-vrf)# route-target import 1:10001
admin@ncs(config-vrf)# route-target export 1:10001
admin@ncs(config-vrf)# description "Customer ACME VPN"
admin@ncs(config-vrf)# top
admin@ncs(config)# /* Interface Configuration */
admin@ncs(config)# devices device PE12 config ios:interface GigabitEthernet 4
admin@ncs(config-if)# description "Connection to Customer ACME - Site 5"
admin@ncs(config-if)# vrf forwarding vpn10001
admin@ncs(config-if)# ip address primary address 172.31.1.1 mask 255.255.255.252
admin@ncs(config-if)# top
admin@ncs(config)# /* BGP Configuration */
admin@ncs(config)# devices device PE12 config ios:router bgp 1 address-family ipv4 unicast vrf vpn10001
admin@ncs(config-router-af)# redistribute connected
admin@ncs(config-router-af)# redistribute static
admin@ncs(config-router-af)# neighbor 172.31.1.2 remote-as 65001
admin@ncs(config-router-af)# neighbor 172.31.1.2 activate
admin@ncs(config-router-af)# neighbor 172.31.1.2 default-originate
admin@ncs(config-router-af)# neighbor 172.31.1.2 as-override
admin@ncs(config-router-af)# neighbor 172.31.1.2 allowas-in as-number 3
admin@ncs(config-router-af)# top
admin@ncs(config)# /* Static Route Configuration */
admin@ncs(config)# devices dev PE12 config ios:ip route vrf vpn10001 192.168.11.0 255.255.255.0 172.31.1.2
The figure illustrates the configuration of the Layer-3 MPLS VPN service through the Cisco NSO CLI:
 VRF instance
 One interface (though the service will support the addition of multiple interfaces). You may also note
that we have changed the addressing policy to simplify the creation of the template-based service model.
 BGP routing protocol for PE-CE peering
 Static route (though the service will support the addition of multiple static routes)
Note The RIP portion of the configuration is not shown in the example above.
Equivalent configuration using the Juniper style CLI:

admin@ncs% /* VRF Configuration */
admin@ncs% edit devices device PE12 config ios:vrf definition
vpn10001
admin@ncs% set rd 1:10001
admin@ncs% set route-target import 1:10001
admin@ncs% set route-target export 1:10001
admin@ncs% set description "Customer ACME VPN"
admin@ncs% top
admin@ncs% /* Interface Configuration */
admin@ncs% edit devices device PE12 config ios:interface
GigabitEthernet 4
admin@ncs% set description "Connection to Customer ACME - Site
5"
admin@ncs% set vrf forwarding vpn10001
admin@ncs% set ip address primary address 172.31.1.1 mask
255.255.255.252
admin@ncs% top
admin@ncs% /* BGP Configuration */
admin@ncs% edit devices device PE12 config ios:router bgp 1
address-family with-vrf ipv4 unicast vrf vpn10001
admin@ncs% set redistribute connected
admin@ncs% set redistribute static
admin@ncs% set neighbor 172.31.1.2 remote-as 65001
admin@ncs% set neighbor 172.31.1.2 activate
admin@ncs% set neighbor 172.31.1.2 default-originate
admin@ncs% set neighbor 172.31.1.2 as-override
admin@ncs% set neighbor 172.31.1.2 allowas-in as-number 3
admin@ncs% top
admin@ncs% /* Static Route Configuration */
admin@ncs% edit devices device PE12 config ios:ip route vrf
vpn10001
admin@ncs% set ip-route-forwarding-list 192.168.11.0
255.255.255.0 172.31.1.2
admin@ncs% top

Device Configuration Using Cisco NSO CLI: XML Output
Cisco IOS Configuration  XML Configuration
admin@ncs% commit dry-run outformat xml <export>
device PE12 { <asn-ip>1:10001</asn-ip>
<ip xmlns="urn:ios"> </export>
<route> </route-target>
<vrf> <rd>1:10001</rd>
<name>vpn10001</name> </definition>
<ip-route-forwarding-list> </vrf>
<prefix>192.168.11.0</prefix> <router xmlns="urn:ios">
<mask>255.255.255.0</mask> <bgp>
<forwarding-address>172.31.1.2</forwarding-address> <as-no>1</as-no>
</ip-route-forwarding-list> <address-family>
</vrf> <with-vrf>
</route> <ipv4>
</ip> <unicast-multicast>unicast</unicast-multicast>
<vrf xmlns="urn:ios"> <vrf>
<definition> <name>vpn10001</name>
<name>vpn10001</name> <neighbor>
<description>Customer ACME VPN</description> <id>172.31.1.2</id>
<address-family> <remote-as>65001</remote-as>
<ipv4/> <as-override/>
</address-family> <default-originate/>
<route-target> <allowas-in>
<import> <as-number>3</as-number>
<asn-ip>1:10001</asn-ip> </allowas-in>
</import> <activate/>
...
...
admin@ncs%
When the configuration is entered into Cisco NSO, we can use the commit dry-run outformat xml
command to generate the XML code that will serve as basis for out mapping template.
Note Only a subset of the XML output is shown in the example above.
Device Configuration Using Cisco NSO CLI: XML Template
Cisco IOS Configuration  XML Configuration  XML Template NIL
<ip xmlns="urn:ios"> <export>
<route> <asn-ip>1:{vpn-id}</asn-ip>
<vrf> </export>
<name>vpn{/vpn-id}</name> </route-target>
<ip-route-forwarding-list> <rd>1:{/vpn-id}</rd>
<prefix>{static/prefix}</prefix> </definition>
<mask>{static/mask}</mask> </vrf>
<forwarding-address>172.31.{/link/site- <router xmlns="urn:ios">
<bgp when="{routing-protocol='bgp'}">
id}.2</forwarding-address>
<as-no>1</as-no>
</ip-route-forwarding-list> <address-family>
</vrf> <with-vrf>
</route> <ipv4>
</ip> <unicast-multicast>unicast</unicast-
<vrf xmlns="urn:ios"> multicast>
<definition> <vrf>
<name>vpn{/vpn-id}</name> <name>vpn{/vpn-id}</name>
<description>L3 VPN for customer <neighbor>
{/customer}</description> <id>172.31.{site-id}.2</id>
<address-family> <remote-as>65001</remote-as>
<ipv4/> <as-override/>
</address-family> <default-originate/>
<route-target> <allowas-in>
<import> <as-number>3</as-number>
<asn-ip>1:{vpn-id}</asn-ip> </allowas-in>
</import> <activate/>
</neighbor>
...
...
The last step is to replace the fixed values from the commit dry-run command with variables (the path to the
YANG model's hierarchy of statements). The data path may not be correct at this time as you may decide to
change it when you are creating the YANG data model.
In the template you can also see the conditional statement for the BGP section of the configuration which
will be processed only if the BGP routing option is chosen for the given PE-CE link. Similarly, we create
conditions for RIP and static routing options (not shown in the example above).
We have also added descriptions to the different portions of the configuration (e.g. interface, VRF) to help in
potential troubleshooting of the service instance throughout its lifetime.
Note Only a subset of the XML output is shown in the example above.

Device Configuration Using Cisco NSO CLI
Cisco IOS XR Configuration
admin@ncs(config)# /* VRF Configuration */
admin@ncs(config)# devices device PE21 config cisco-ios-xr:vrf vpn10001
admin@ncs(config-vrf)# address-family ipv4 unicast import route-target 1:10001
admin@ncs(config-import-rt)# address-family ipv4 unicast export route-target 1:10001
admin@ncs(config-export-rt)# description "Customer ACME VPN"
admin@ncs(config-vrf)# top
admin@ncs(config)# /* Interface Configuration */
admin@ncs(config)# devices device PE21 config cisco-ios-xr:interface GigabitEthernet 0/0/0/1
admin@ncs(config-if)# description "Connection to Customer ACME - Site 9"
admin@ncs(config-if)# vrf vpn10001
admin@ncs(config)# ipv4 address ip 172.31.1.5 mask 255.255.255.252
admin@ncs(config)# top
admin@ncs(config)# /* BGP Configuration */
admin@ncs(config)# devices device PE21 config cisco-ios-xr:router bgp 1 vrf vpn10001
admin@ncs(config-bgp-vrf)# rd 1:10001
admin@ncs(config-bgp-vrf)# address-family ipv4 unicast redistribute connected
admin@ncs(config-bgp-af)# address-family ipv4 unicast redistribute static
admin@ncs(config-bgp-vrf)# exit
admin@ncs(config-bgp-vrf)# neighbor 172.31.1.6 address-family ipv4 unicast route-policy in pass
admin@ncs(config-bgp-nbr-af)# neighbor 172.31.1.6 address-family ipv4 unicast route-policy out pass
admin@ncs(config-bgp-nbr-af)# neighbor 172.31.1.6 address-family ipv4 unicast as-override
admin@ncs(config-bgp-nbr-af)# neighbor 172.31.1.6 address-family ipv4 unicast allowas-in 3
admin@ncs(config-bgp-nbr-af)# neighbor 172.31.1.6 address-family ipv4 unicast default-originate
admin@ncs(config)# top
admin@ncs(config)# /* Static Route Configuration */
admin@ncs(config)# devices device PE21 config cisco-ios-xr:router static address-family ipv4 unicast
admin@ncs(config-static-afi)# routes 192.168.21.0/24 GigabitEthernet0/0/0/1 address 172.31.1.6
admin@ncs(config-static-afi)# top
Repeat the process for each device type. In the example we have the same service configuration for Cisco
IOS XR.
Note The RIP portion of the configuration is not shown in the example above.
Equivalent configuration using the Juniper style CLI:

admin@ncs% /* VRF Configuration */
admin@ncs% edit devices device PE21 config cisco-ios-xr:vrf vrf-
list vpn10001
admin@ncs% set address-family ipv4 unicast import route-target
address-list 1:10001
admin@ncs% set address-family ipv4 unicast export route-target
address-list 1:10001
admin@ncs% set description "Customer ACME VPN"
admin@ncs% top
admin@ncs% /* Interface Configuration */
admin@ncs% edit devices device PE21 config cisco-ios-
xr:interface GigabitEthernet 0/0/0/1
admin@ncs% set description "Connection to Customer ACME - Site
9"
admin@ncs% set vrf vpn10001
admin@ncs% set ipv4 address ip 172.31.1.5 mask 255.255.255.252
admin@ncs% top
admin@ncs% /* BGP Configuration */
admin@ncs% edit devices device PE21 config cisco-ios-xr:router
bgp bgp-no-instance 1 vrf vpn10001
admin@ncs% set rd 1:10001
admin@ncs% set address-family ipv4 unicast redistribute
connected
admin@ncs% set address-family ipv4 unicast redistribute static
admin@ncs% set neighbor 172.31.1.6 address-family ipv4 unicast
route-policy in pass
route-policy out pass
as-override
allowas-in 3
default-originate
admin@ncs% top
admin@ncs% /* Static Route Configuration */
admin@ncs% edit devices device PE21 config cisco-ios-xr:router
static address-family ipv4 unicast
admin@ncs% set routes 192.168.21.0/24 GigabitEthernet0/0/0/1
address 172.31.1.6
admin@ncs% top

Device Configuration Using Cisco NSO CLI: XML Output
Cisco IOS XR Configuration  XML Configuration
admin@ncs% commit dry-run outformat xml <router xmlns="http://tail-f.com/ned/cisco-ios-xr">
device PE21 { <bgp>
<vrf xmlns="http://tail-f.com/ned/cisco-ios-xr"> <bgp-no-instance>
<vrf-list> <id>1</id>
<name>vpn10001</name> <vrf>
<description>Customer ACME VPN</description> <name>vpn10001</name>
<address-family> <neighbor>
<ipv4> <id>172.31.1.6</id>
<unicast> <remote-as>65001</remote-as>
<import> <address-family>
<route-target> <ipv4>
<address-list> <unicast>
<name>1:10001</name> <route-policy>
</address-list> <direction>in</direction>
</route-target> <name>pass</name>
</import> </route-policy>
<export> <route-policy>
<route-target> <direction>out</direction>
<address-list> <name>pass</name>
<name>1:10001</name> </route-policy>
</address-list> <as-override/>
</route-target> <default-originate/>
</export> </unicast>
</unicast> </ipv4>
</ipv4> </address-family>
</address-family> ...
... admin@ncs%
Again generate the XML configuration output using the commit dry-run outformat xml CLI command.
Device Configuration Using Cisco NSO CLI: XML Template
Cisco IOS XR Configuration  XML Configuration  XML Template
<vrf xmlns="http://tail-f.com/ned/cisco-ios-xr"> <router xmlns="http://tail-f.com/ned/cisco-ios-xr">
<vrf-list> <bgp when="{routing-protocol='bgp'}">
<name>vpn{/vpn-id}</name> <bgp-no-instance>
<description>L3VPN for customer <id>1</id>
{/customer}</description> <vrf>
<address-family> <name>vpn{/vpn-id}</name>
<ipv4> <neighbor>
<unicast> <id>172.31.{site-id}.2</id>
<import> <remote-as>65001</remote-as>
<route-target> <address-family>
<address-list> <ipv4>
<name>1:{/vpn-id}</name> <unicast>
</address-list> <route-policy>
</route-target> <direction>in</direction>
</import> <name>pass</name>
<export> </route-policy>
<route-target> <route-policy>
<address-list> <direction>out</direction>
<name>1:{/vpn-id}</name> <name>pass</name>
</address-list> </route-policy>
</route-target> <as-override/>
</export> <default-originate/>
</unicast> </unicast>
</ipv4> </ipv4>
</address-family> </address-family>
... ...
Replace the static values with the expected data path to the service model.

Service Model
This topic builds on top of the informal service design whether it was derived in the top-down
or bottom-up approach. The topic provides the detailed steps needed to create a service design
using the YANG modeling language.
Layer 3 MPLS VPN Service Model

Data path in l3mplsvpn:
 vpn- id
 vpn- name
L l3mplsvpn
 customer (reference)
 link/ K vpn- id L vpn- name R customer
 link/interface L link
 link/routing- protocol K link- id U linterface U routing- protocol R device

 link/device (reference)
L static
 link/static/
K prefix K mask
 link/static/prefix
 link/static/mask
In the last step we start creating the formal YANG service model based on the information that we have
gathered so far. The figure illustrates the hierarchy of YANG statements and the types of data.
module l3mplsvpn{
namespace "http://com/example/l3mplsvpn"; YANG statements representing our
prefix l3mplsvpn;
import ietf-inet-types { prefix inet; } informal design:
import tailf-common { prefix tailf; }  There can be many service instances
list l3mplsvpn {
 Each instance can have one or more PE-
leaf vpn-name { ... } CE links
leaf vpn-id { ... }
leaf customer { ... }  If static routing is chosen there may be
list link { one or more static routes
leaf site-id { ... }
leaf device { ... }
leaf interface { ... }
leaf routing-protocol { ... }
list static {
leaf prefix { ... }
leaf mask { ... }
}
}
}
}
}
The YANG model above illustrates the main statements that describe our informal design. The above
statements should provide enough information to describe the service and pass the necessary parameters to
the device manager for the service to be properly configured on network devices.

...
list l3mplsvpn {
key vpn-id;
The first part of the service model
unique "device loopback-intf";
unique "ip-address";
contains parameters describing the
service instance:
uses ncs:service-data;
ncs:servicepoint "l3mplsvpn";  Service instance name
leaf vpn-name {
tailf:info "Service Instance Name";  Service instance ID
type string;
}  Customer reference
leaf vpn-id {
tailf:info "Service Instance ID";
type uint32 {
range "10001..19999";
}
}
leaf customer {
tailf:info "VPN Customer";
type leafref {
path
"/ncs:customers/ncs:customer/ncs:id";
}
}
...
The first part of the YANG model describes the service instance. This portion has three parameters (leafs):
 vpn-name:
— As you can see from the example we have also added another leaf which is used to hold the
textual description of the service instance without having any other (i.e. technical) meaning.
 vpn-id
— This parameter is used to uniquely identify a service instance and is reused late on for some
other configuration parameters (e.g. to constrict the VRF name).
 customer
— This leaf is linked to the list of customers in the NSO. Since this is a customer service it is
expected that a service instance will be associated with a customer.
...
list link {
tailf:info "PE-CE Attachment Point";
The second part of the service model
key link-id; contains the list statement for the PE- CE
leaf link-name { link(s)
tailf:info "Link Name";
type string;
} Each link provides a connection to a
leaf link-id { customer site:
tailf:info "Link ID";
type uint32 {  Site name
range "1..255";
}
}  Site ID
leaf device {  PE router
tailf:info "PE Router";
type leafref {  Interface number
}
}  (continued on next slide)
leaf interface {
tailf:info "Customer Facing Interface";
type string;
}
...
The next part contains a list of links that define individual PE-CE connections. Each link has the following
parameters:
 link-name
— Just like the service instance itself, we have added another parameter that can hold textual
information about the provisioned link. This parameter holds no special technical meaning.
 link-id
— This parameter is used to hold the unique link identifier. Earlier, we changed the addressing
rules to accommodate the usage of a template-based service model. This ID is used as third octet
in the PE-CE address (hence the range 1..255). Our choice, however, has an impact on the
scalability of the service as we can see that we cannot provision more than 255 links inside a
single VPN.
 device
— The device is the reference to the service provider routers where we configure these services.
 interface
— This parameter is used to identify the interface that connects to the customer device.
 (continued on next page)

...
leaf routing-protocol { The second part of the service model
tailf:info "Routing option on PE-CE link";
type enumeration { contains the list statement for the PE- CE
enum bgp;
enum rip; link(s)
enum static;
}
} Each link provides a connection to a
customer site:
list static {
tailf:info "Static Route";  Site name
key prefix;
when "../routing-protocol='static'";  Site ID
leaf prefix {  PE router
tailf:info "Static Route Prefix";
type inet:ipv4-address;  Interface number
}
 Routing option: BGP, RIP or static routes
leaf mask {
tailf:info "Static Route Subnet Mask";
 Static route(s) in case the chosen routing option
type inet:ipv4-address; is static route:
}
}  Prefix
...
 Subnet mask
 routing-protocol
— This parameters allows the operator to choose the routing option that will be used with CE
devices: BGP, RIP version 2 or static routes.
 static
— The last parameter is a list and it contains the parameters needed to configure a static route
(prefix and mask; the next-hop address is dynamically determined in the XML template). Note
that there is a when statement that only makes the static list available if the chosen routing
option is static.
Layer- 3 MPLS VPN Example Analysis: Complexity Reduction
Devices: 10 Element Management Using Native Service Management Using Cisco
PE- CE links: 20 Device CLI NSO CLI / GUI
Routing Scenario Total CLI lines
BGP 250 20
RIP 190 20
Static (one per link) 170 20
Routing Scenario Total service parameters
BGP 140 60
RIP 100 60
Static (one per link) 160 100
 90% reduction in CLI commands

 35% - 60% reduction in number of parameters
 YANG modeling used to ensure parameter validity
If we analyze the whole process and look at the original configuration data and then compare it with the final
result, we can see that from the operations perspective we have significantly reduced the number of
commands and parameters.
In the sample calculation we use a Layer-3 MPLS VPN setup where we have 20 PE-CE links attached to 10
PE routers. That would require us to enter 250 CLI commands on routers in the case of using BGP for
signaling. When using the Cisco NSO CLI and the previously described service, we only need to enter 20
Cisco NSO CLI commands. Additionally, we have reduced the number of parameters and also provided
safeguards that minimize the risk of the operator misconfiguring the parameters.

Simple VPLS Example Analysis: Complexity Reduction
Cisco IOS CLI: Cisco NSO Device CLI:
devices device PE13 config ios:l2 vfi 123 autodiscovery bridge-domain id 123
PE13: devices device PE13 config ios:l2 vfi 123 autodiscovery vpn id 123
interface GigabitEthernet4 devices device PE13 config ios:interface GigabitEthernet 4 service instance 123 ethernet bridge-domain id 123
service instance 123 ethernet devices device PE13 config ios:interface GigabitEthernet 4 service instance 123 ethernet encapsulation untagged
encapsulation untagged
bridge-domain 123 devices device PE31 config ios:l2 vfi 123 autodiscovery bridge-domain id 123
! devices device PE31 config ios:l2 vfi 123 autodiscovery vpn id 123
l2 vfi 123 autodiscovery devices device PE31 config ios:interface GigabitEthernet 4 service instance 123 ethernet bridge-domain id 123
vpn id 123 set devices device PE31 config ios:interface GigabitEthernet 4 service instance 123 ethernet encapsulation untagged
bridge-domain 123
! devices device PE32 config ios:l2 vfi 123 autodiscovery bridge-domain id 123
devices device PE32 config ios:l2 vfi 123 autodiscovery vpn id 123
PE31: devices device PE32 config ios:interface GigabitEthernet 4 service instance 123 ethernet bridge-domain id 123
interface GigabitEthernet4 devices device PE32 config ios:interface GigabitEthernet 4 service instance 123 ethernet encapsulation untagged
service instance 123 ethernet
bridge-domain 123
! Service Model Design
l2 vfi 123 autodiscovery
vpn id 123
bridge-domain 123
! Cisco NSO Service CLI: Expose to OSS/ BSS or
services vpls Cust1 service-id 123 attachments PE13 4
services vpls Cust1 service-id 123 attachments PE31 4 custom web portal (e.g. via
PE32:
interface GigabitEthernet4 services vpls Cust1 service-id 123 attachments PE32 4 REST)
service instance 123 ethernet
bridge-domain 123
!
l2 vfi 123 autodiscovery
70 CLI lines  20 CLI lines
vpn id 123
bridge-domain 123 5 parameters  3 parameters
!
The figure illustrates another example where we use the simplest version of VPLS to implement a Layer-2
MPLS VPN for 20 sites connected to 10 PE routers. Similarly we have achieved a great reduction in the
number of commands and parameters while also improving the robustness of the solution.
Summary
 Learn to design and implement services with NSO
 Augment the classic service design by introducing service modeling
 Make use of architect and engineering expertise to derive quality device configurations
 Thoroughly test the service model in a lab or using and emulated environment
References

Lesson 3-4
Service Management
Overview
This lesson introduces how service management is done within Cisco Network Services
Orchestrator. It explains how the Service Manager can be used both through CLI and WebUI.
Objectives
 Manage services
 Deploy, remove, re-deploy service instances
Service Management Tasks
This topic describes how NSO CLI and WebUI can be used to fulfill the service management
operations.
Service Management
 Service modeling
 Mapping to device model
 Service activation
 Device “effects” Service Manager
 Service dry-run
 Service check-sync CDB
Mapping Logic
Transaction
 Service restoration Manager
 Service testing Device Manager
 Mapping service to device
 Aggregated operational data
 Notifications
Service management consists of many different types of actions. In the previous lesson we already learned
many of the tasks when we modeled a service and applied it to the network. A number of other tasks are
available to handle service management such as checking the synchronization status, deleting a service or
just un-deploying a service.
Service Management Options
 NSO CLI: CLI WebUI API
 Cisco style
 Juniper style
 NSO WebUI Service Manager

 An external system using any
of the available APIs: CDB
Mapping Logic
Transaction
 REST Manager
 MAAPI Device Manager
 NETCONF
 SNMP
 …
We have seen that there are two major types of CLI in NSO to accommodate the majority of network
operators who are familiar with Cisco CLI, Juniper CLI or both. Additionally, you can manage services
through the WebUI that is automatically augmented when you add a service or you may even further
augment it by creating other objects or even integrating your own WebUI.
NSO is also very extensible and it can be integrated with other systems using a number of APIs mentioned
earlier.

NSO CLI and WebUI
 Main components:
 Services
 Devices Service Manager
 Other components Mapping Logic

CDB
Transaction
 Customers Manager
 Templates Device Manager
 Alarms
The main components of the service management are the same as the main components of the system:
 Services which are handled by the service manager.
 Devices which are handled by the device manager.
Additionally, there are a number of other components that help with the manageability of services
(customers, templates, alarms, etc.).
NSO CLI and WebUI for Services
 No extra development required to provide a CLI or WebUI for services
 Both CLI and WebUI options are dynamically created based on service
packages
 YANG annotations can be used to influence the CLI and WebUI (e.g. tailf:info to
provide syntax help)
YANG Service Model NSO CLI
leaf vpn-id { admin@ncs(config)# services l3mplsvpn ?
tailf:info "Service Instance ID"; Possible completions:
type uint32 { Service Instance ID (10001 to 19999) 10001 range
range "10001..19999"; admin@ncs(config)#
}
}
Whenever you design a new service you will see the service name and parameters become available in the
CLI and WebUI. You may also augment the way the WebUI and CLI provide this information by using a
number of available annotations.
Use man tailf_yang_cli_extensions shell command to get help on the available NSO annotations.

Service Configuration Maintenance Tools (Cont.)
CDB
Check Sync Device 1 S1 S2
configuration
S1 Device 1
Service instance
configuration S2
Device 2 S2 S2
Deep Check Sync
configuration
Device 2
admin@nso# service l3mplsvpn S1 check-sync

admin@nso# service l3mplsvpn S2 deep-check-sync
 Internal sync check between service configuration and device-specific configuration as a result
of the service-to-device mapping logic
 Extend sync check to the actual device configuration
deep-check-sync
This will validate if the actual devices are configured according to the service. Note that there are out-format
options to see the diff. Reconcile using service re-deploy.
NSO: CLI (Cisco Style)
Edit an existing service instance
or create a new one
admin@ncs(config)# services l3mplsvpn 10002 link 3 interface ...

... Check service synchronization
admin@ncs(config)# services l3mplsvpn 10001 check-sync status to mapped device
in-sync true configuration
admin@ncs(config)# services l3mplsvpn 10001 deep-check-sync Check service synchronization

in-sync true status to actual device
configuration
admin@ncs(config)# services l3mplsvpn 10001 re-deploy
Re-deploy the service
admin@ncs(config)# services l3mplsvpn 10001 un-deploy
instance
admin@ncs(config)# no services l3mplsvpn 10002
Un-deploy the service

instance (i.e. remove from
Delete the service instance devices, but keep in CDB)
The NSO CLI supports two styles:

 Cisco style (shown in the figure)
 Juniper style (shown on the next page)
Every NSO operator that uses the CLI can use their preferred style.
The following example illustrates how the same can be accomplished using the Juniper style CLI:
admin@ncs% set services l3mplsvpn 10002 link 3 interface ...
[ok][2014-11-09 11:39:24]
[edit]
admin@ncs% request services l3mplsvpn 10002 check-sync
in-sync true
[ok][2014-11-09 11:40:01]
[edit]
admin@ncs% request services l3mplsvpn 10001 re-deploy
No modifications to commit.
[ok][2014-11-09 11:40:14]
[edit]
admin@ncs% request services l3mplsvpn 10001 un-deploy
[ok][2014-11-09 11:40:49]
[edit]
admin@ncs% delete services l3mplsvpn 10002
[ok][2014-11-09 11:39:13]
[edit]

Comparing Configurations: Service or Device
CDB
Get Modifications Device 1 S1 S2
configuration
S1 Device 1
Service instance
configuration S2
Device 2 S2 S2
configuration Compare
Device 2
admin@nso# service l3mplsvpn S1 get-modifications

admin@nso# devices device PE11 compare-config
 Get device modifications made by a service instance

 Get discrepancies between CDB version of device configuration and actual device configuration
The figure illustrates two configuration comparison options:

 Display the device configuration that is created based on a service instance.
 Display the differences between the CDB version of device configuration and actual device
configuration.
Service Lifecycle Management
Guidelines
This topic provides some general guidelines for development and maintenance of YANG
models.
Automatic Service Package Upgrade
 Every package reload action triggers a service upgrade process

 Automatic service upgrade succeeds in the following cases:
 Deleted nodes: always succeeds; deletes nodes from data tree
 Added nodes: succeeds if not mandatory without default
 Re-ordered nodes: always succeeds
 Type changes: succeeds if smart type conversion succeeds or there is a default value
 Key changes: succeeds if modified key leaf is still unique
 Default values: always succeeds and changes values only to those leafs that had a default
value
CDB can automatically handle the following changes to the schema:

Deleted elements
When an element is deleted from the schema, CDB simply deletes it (and any children) from
the database.
Added elements
If a new element is added to the schema it needs to either be optional, dynamic, or have a
default value. New elements with a default are added set to their default value. New dynamic or
optional elements are simply noted as a schema change.
Re-ordering elements
An element with the same name, but in a different position on the same level, is considered to
be the same element. If its type hasn't changed it will retain its value, but if the type has
changed it will be upgraded as described below.
Type changes
If a leaf is still present but its type has changed, automatic coercions are performed, so for
example integers may be transformed to their string representation if the type changed from e.g.
int32 to string. Automatic type conversion succeeds as long as the string representation of the
current value can be parsed into its new type. (Which of course also implies that a change from
a smaller integer type, e.g. int8, to a larger type, e.g. int32, succeeds for any value - while the
opposite will not hold, but might!). If the coercion fails, any supplied default value will be
used. If no default value is present in the new schema the automatic upgrade will fail. Type

changes when user-defined types are used are also handled automatically, provided that some
straightforward rules are followed for the type definitions. Read more about user-defined types
in the confd_types(3) manual page, which also describes these rules.
Hash changes
When a hash value of particular element has changed (due to an addition of, or a change to, a
tailf:id-value statement) CDB will update that element.
Key changes
When a key of a list is modified, CDB tries to upgrade the key using the same rules as
explained above for adding, deleting, re-ordering, change of type, and change of hash value. If
automatic upgrade of a key fails the entire list instance will be deleted.
Default values
If a leaf has a default value, which has not been changed from its default, then the automatic
upgrade will use the new default value (if any). If the leaf value has been changed from the old
default, then that value will be kept.
Adding / Removing namespaces
If a namespace no longer is present after an upgrade, CDB removes all data in that namespace.
When CDB detects a new namespace, it is initialized with default values.
Changing to/from operational
Elements that previously had config false set that are changed into database elements will be
treated as added elements. In the opposite case, where data elements in the new data model are
tagged with config false, the elements will be deleted from the database.
Callpoint changes
CDB only considers the part of the data model in YANG modules that do not have external
data callpoints. But while upgrading, CDB does handle moving subtrees into CDB from a
callpoint and vice versa. CDB simply considers these as added and deleted schema elements.
Thus an application can be developed using CDB in the first development cycle. When the
external database component is ready it can easily replace CDB without changing the schema.
Should the automatic upgrade fail, exit codes and log-entries will indicate the reason.
Service Package Upgrade Actions
Service create Mapping upgrade Service redeploy Device

model logic Config Config
(XML and/or
(YANG)
Java)
(CDB) (CDB)
After change: After XML change:

 Recompile  Reload
 Reload  Re-deploy if needed
After Java change:

 Recompile
 Reload
 Re-deploy if needed
 A re-deploy of the upgraded service is needed when the service change results
in changed device commands
The figure illustrates the path of data from the service model down to the device configuration. Any change
in any of the involved pieces of logic may require some actions in order to make those changes active.

Service Model Versioning
Should: May:
 Add a revision statement on top  Add new statements and non-
mandatory data definitions
 Update organization, contact,
etc.  Add mandatory data definitions
within new if-feature statements
 Do not rename module,
namespace or prefix or
 Do not remove obsolete  Use proper service upgrade

definitions procedures
 Do not change the hierarchy of

nodes
This and the next two pages provide an overview of general guideline to follow in order to simplify the
development and maintenance of solutions based on YANG service models. The "should" and "may" are not
the same as "must" but following the guidelines may prove to be useful especially when modifying
(upgrading) service models.
Service Model Versioning
May: May:
 Add or update a status  Change mandatory to false (or
statement: current  deprecated remove it)
 obsolete
 Remove or relax min- & max-
 Expand allowed range, length, elements
pattern
 Add or clarify a description
 Add a default (but not change it!) without changing the semantics
 Add units, add or update a  Change state data to optional
reference configuration
 Remove an if-feature
In general, always consider what impact a changed model will have on the service upgrade.

IETF Modeling Recommendations
Should: Should:
 Describe module, security  Use ranges, length restrictions,
considerations, references, patterns
definitions, …
 Do not use signed types unless
 Only one node definition on top negative values needed
level to prevent clutter (e.g.
 When possible, use standard
container)
types (e.g. defined in RFC 6021)
 Top level data definitions
 Make your own reusable type
optional
modules
 Use identityref instead of
enumeration for non-static data
Also follow the guidelines provided by IETF's in RFC 6087 and make use of IETF's data type defined in
RFC 6021 as well as all extensions provided by NSO.
Summary
 Operations characteristics
 Simplicity and reliability: operator exposed to the optimal set of service parameters and
reliable actions
 Performance characteristics
 Simplicity: service manager is only concerned with service model, not with service
instance actions (create, delete, modify)
 Optimization: only the minimum set of commands is sent to the devices
References
 IETF RFCs 6087, 6020 and 6021

Lesson 4-1
Cisco NSO Integration Options

Overview
This lesson describes the available northbound interfaces that allow the Cisco Network
Services Orchestrator system to be integrated with other operation support
systems (OSS)/network management systems (NMS) or provide scripting and automation to
operators.
Objectives
 Identify Cisco NSO northbound interfaces and outline APIs
 Identify use cases for different integration options
 Understand capabilities and limitation of APIs
This topic describes Cisco NSO integration options.
Typical Integration Requirements
 Integration with other OSS/NMS systems

 Customization of user interface to fit business processes
 Task automation using scripts (e.g. triggered, scheduled)
 Bulk data import or export
Any management system must be placed into an existing environment with existing other systems and
established business processes. As such we are always faced with a number of requirements pertaining to
integration of a new system with the relevant existing systems in order to abide by existing business process
rules or optimize them.
Some of the more common integration requirements are:
 Integration with other existing OSS/NMS.
 Customization of user interface to fit business processes.
 Task automation using scripts (e.g. triggered, scheduled).
 Bulk data import or export.
Engineer
NSO JAVA/JavaScrip
t
Northbound APIs
Package Any scripting

Script API
Service language
Models Manager
Core Alarm Developer Java or Python
Mapping Logic Manager API extensions
Engine
Device Device
CDB Notification
NETCONF REST CLI OpenFlow etc.
Up to this point we have shown how to use the NSO CLI and WebUI to perform configuration tasks of
"southbound" devices. Cisco NSO provides several northbound programmatic interfaces that a network
engineer can use to automate tasks.
NSO Northbound Scripting Interfaces:
 CLI: This is a network wide CLI that provides transactions across multiple devices and full support for
the service models. Also this enables network automation by scripting towards the network and the
network services in a unified CLI rather than towards the devices' native CLIs.
 REST: The rest interface provides the complete model available as HTTP GET, PUT and other
operations. The data is available as XML and JavaScript Object Notation (JSON).
 NETCONF: This gives other OSS applications a Network Configuration Protocol (NETCONF)
interface to the devices and services managed by NSO.
 MAAPI: General Management Agent Application Programming Interface (MAAPI) comes in several
flavors. MAAPI is available as command line utilities, C-API, Java API, and a Python API. This lesson
will illustrate the use of command-line utilities.
 JavaScript: The JavaScript interface is used to build custom Web interfaces. The interface is AJAX
based so that true clients can be built, including for example event subscriptions without round-trips to
the web server.
 Scripts: Cisco NSO also supports what are called "plug-and-play" scripts. Plug-and-play scripts can be
dropped in a running NSO system. The scripts will extend the CLI with new functions. Plug-and-play
scripts are only available in the NSO CLI. They are often implemented as shell scripts that calls MAAPI
functions. Also note that NSO can be used as a development platform to build custom network
management applications.
 SNMP: NSO can present operational data over Simple Network Management Protocol (SNMP) to
upper layer management systems. This is useful for example in the case of alarms and performance data.
There is also a dedicated SNMP Alarm MIB for the NSO Alarm Manager.
© 2016 Cisco Systems, Inc. System Administration and Integration 4-3

Cisco NSO NETCONF API
This topic describes use of NETCONF northbound application programming interface (API)
with Cisco NSO.
Cisco NSO NETCONF API

 Use cases:
 Integration with other OSS/NMS Any NETCONF client
systems
 Task automation using scripts
 Bulk data import or export SSH (default)
Plain TCP
 NSO provides a NETCONF client:
NETCONF 1.0
 netconf-console: client application in NETCONF Server NETCONF 1.1
Python W3C XPath 1.0
 Any NETCONF client can be used
CDB
NETCONF is the preferred integration API when integrating other OSS/NMS systems in front of NSO as
long as they support the protocol. NSO supports a number of other APIs discussed later which can be used in
case NETCONF is not supported.
The NSO NETCONF north bound API can be used by arbitrary NETCONF clients. The installation of NSO
also provides a NETCONF client:
 netconf-console
This is a very simple Python based NETCONF client that is shipped as source code in the NSO
distribution.
Other NETCONF clients will work too, as long as they adhere to the NETCONF protocol. When integrating
NSO into larger OSS/NMS environments, the NSO NETCONF API is a good choice of integration point.
Cisco NSO NETCONF API Example
cisco@nso:~$ netconf-console --get-config -x /services/l3mplsvpn[vpn-id='10001']
<?xml version="1.0" encoding="UTF-8"?>
<rpc-reply xmlns="urn:ietf:params:xml:ns:netconf:base:1.0" message-id="1">
<data>
<services xmlns="http://tail-f.com/ns/ncs">
<l3mplsvpn xmlns="http://com/example/l3mplsvpn">
<vpn-id>10001</vpn-id>
<vpn-name>Primary VPN</vpn-name>
<customer>ACME</customer> Main NETCONF options:
<link>
<link-id>2</link-id> --get
<link-name>Central Site</link-name> --get-config
<device>PE12</device>
<interface>4</interface> --edit-config
<routing-protocol>bgp</routing-protocol>
</link>
 The –x option can be used to reference data by XPath

The figure illustrates the use of the netconf-console command to retrieve service configuration information.
XPath can be used to retrieve the required data.
NETCONF Console command syntax and options

Usage: netconf-console [-h | --help] [options] [cmdoptions | <filename> | -]
Where <filename> is a file containing a NETCONF XML command session. If <filename> is not given, one
of the Command Options must be given. Filename - means standard input.
Options:
-h, --help show this help message and exit
-v VERSION, --version=VERSION
force NETCONF version 1.0 or 1.1
-u USERNAME, --user=USERNAME username
-p PASSWORD, --password=PASSWORD password
--proto=PROTO Which transport protocol to use, one of ssh or tcp
--host=HOST NETCONF agent hostname
--port=PORT NETCONF agent SSH port
-s STYLE, --outputStyle=STYLE Display output in: raw, plain, pretty, all, or noaaa format
--iter=ITER Sends the same request ITER times. Useful only intest scripts
-i, --interactive

SSH Options:
--privKeyType=PRIVKEYTYPE type of private key, rsa or dss
--privKeyFile=PRIVKEYFILE file which contains the private key
TCP Options:
-g GROUPS, --groups=GROUPS Set group membership for user - comma separated string
-G SUPGROUPS, --sup-groups=SUPGROUPS Set supplementary UNIX group ids for user – comma separated
string of integers
NETCONF Command Options:

--hello Connect to the server and print its capabilities
--get Takes an optional -x argument for XPath filtering
--get-config Takes an optional --db argument, default is 'running', and an optional -x argument for XPath filtering
--db=DB Database for commands that operate on a database.
--with-defaults=WDEFAULTS One of 'explicit', 'trim', 'report-all' or 'report- all-tagged'. Use with --get, --get-
config, or --copy-config.
--with-inactive Send with-inactive parameter. Use with --get, --get-config, --copy-config, or --edit-config.
-x, --xpath XPath filter to be used with --get, --get-config, and --create-subscription
--kill-session=KILL_SESSION Takes a session-id as argument.
--discard-changes
--commit
--validate Takes an optional --db argument, default is 'running'.
--copy-running-to-startup
--copy-config=COPY Takes a filename as argument. The contents of the file is data for a single NETCONF copy-config
operation (put into the <config> XML element). Takes an optional --db argument, default is 'running'.
--edit-config=EDIT Takes a filename as argument. The contents of the file is data for a single NETCONF edit-config operation
(put into the <config> XML element). Takes an optional --db argument, default is 'running'.
--get-schema=GET_SCHEMA Takes an identifier (typically YANG module name) as parameter
--create-subscription=CREATE_SUBSCRIPTION Takes a stream name as parameter, and an optional –x for

XPath filtering
--rpc=RPC Takes a filename as argument. The contents of the file is a single NETCONF rpc operation (w/o the
surrounding <rpc>).
Cisco NSO CLI API
This topic describes the Cisco NSO CLI API that allows external usage of CLI commands.
Cisco NSO CLI API

Use cases for local NSO system access: Automated tasks
 Shell command to access the Cisco
NSO CLI
 Within other scripts to automate tasks
 Populate CDB with data needed for CLI
services
 Bulk access to data for export and ncs_cli
CDB
processing
ncs_cmd
ncs_load
CLI access, scripts,

data transfer
There are two options available to access operational and configuration data in NSO:
 ncs_cli: This shell command allows access using the NSO CLI commands. Take into consideration that
this command provides local access to the CLI on the NSO server without additional security. A remote
access to CLI should use the standard approach by using Secure Shell (SSH).
 ncs_cmd: This shell command allows access using the low-level Configuration Database (CDB)
commands.
 ncs_load: This shell command allows the loading and saving of NSO configurations.
Cisco NSO CLI API
The ncs_cli program is a C frontend to the NSO CLI engine. The ncs_cli program connects to
NSO and basically passes data back and forth from the user to NSO. The ncs_cli command can
be invoked from the command line. If so, no authentication is done.
NAME
ncs_cli - Frontend to the NSO CLI engine
SYNOPSIS
ncs_cli [options] [File]ncs_cli [--help] [--host Host] [--ip IpAddress | IpAddress/Port] [--
address Address] [--port PortNumber] [--cwd Directory] [--proto tcp | ssh | console] [--
interactive] [--noninteractive] [--user Username] [--uid UidInt] [--groups Groups] [--
gids GidList] [--gid Gid] [--opaque Opaque] [--noaaa]
DESCRIPTION
The ncs_cli program is a C frontend to the NSO CLI engine. The ncs_cli program connects to
NSO and basically passes data back and forth from the user to NCS.ncs_cli can be invoked

from the command line. If so, no authentication is done. The archetypical usage of ncs_cli is to
use it as a login shell in /etc/passwd, in which case authentication is done by the login
program.
OPTIONS
-h, --helpDisplay help text.
-H, --host HostNameGives the name of the current host. The ncs_cli program will use the value
of the system call gethostbyname() by default. The host name is used in the CLI prompt.
-i, --ip IpAddress | IpAddress/Port Set the IP (or IP address and port) which NSO reports that
the user is coming from. The ncs_cli program by default tries to determine this automatically
by reading theSSH_CONNECTION environment variable.
-A, --address AddressCLI address to connect to. The default is 127.0.0.1. This can be controlled
by either this flag, or the UNIX environment variable NCS_IPC_ADDR. The -A flag takes
precedence.
-P, --port PortNumberCLI port to connect to. The default is the NSO IPC port, which
is 4569 This can be controlled by either this flag, or the UNIX environment
variable NCS_IPC_PORT. The -P flag takes precedence.
-c, --cwd DirectoryThe current working directory for the user once in the CLI. All file
references from the CLI will be relative to the cwd. By default the value will be the actual cwd
wherencs_cli is invoked.
-p, --proto ssh | tcp | consoleThe protocol the user is using. If SSH_CONNECTION is set, this
defaults to "ssh", otherwise "console".
-n, --interactiveThis forces the CLI to run in interactive mode. In non interactive mode, the CLI
never prompts the user for any input. This flag can sometimes be useful in certain CLI scripting
scenarios.
-N, --noninteractiveThis forces the CLI to run in non interactive mode. See ??? for further info.
-u, --user UserIndicates to NSO which username the user has. This defaults to the username of
the invoker.
-U, --uid UidIndicates to NSO which uid the user has.
-g, --groups GroupListIndicates to NSO which groups the user are a member of. The parameter
is a comma separated string. This defaults to the actual UNIX groups the user is a member of.
The group names are used by the AAA system in NSO to authorize data and command access.
-D, --gids GidListIndicates to NSO which secondary group ids the user shall have. The
parameter is a comma separated string of integers. This defaults to the actual secondary UNIX
group ids the user has. The gids are used by NSO when NSO executes commands on behalf of
the user.
-G, --gid GidIndicates to NSO which group id the user shall have. This defaults to the actual
UNIX group id the user has. The gid is used by NSO when NSO executes commands on behalf
of the user.
-O, --opaque OpaquePass an opaque string to NSO. The string is not interpreted by NSO, only
made available to application code. See "built-in variables"
in clispec(5) andmaapi_get_user_session_opaque() in confd_lib_maapi(3). The string can be
given either via this flag, or via the UNIX environment variable NCS_CLI_OPAQUE. The -
Oflag takes precedence.
--noaaaCompletely disables all AAA checks for this CLI. This can be used as a disaster
recovery mechanism if the AAA rules in NSO have somehow become corrupted.
ENVIRONMENT VARIABLES
NCS_IPC_ADDRWhich IP address to connect to.
NCS_IPC_PORTWhich TCP port to connect to.
SSH_CONNECTIONSet by openssh and used by ncs_cli to determine client IP address etc.
TERMPassed on to terminal aware programs invoked by NSO.
EXIT CODES
0 Normal exit
1 Failed to read user data for initial handshake.
2 Close timeout, client side closed, session inactive.
3 Idle timeout triggered.
4 TCP level error detected on daemon side.
5 Internal error occurred in daemon.
5 User interrupted clistart using special escape char.
6 User interrupted clistart using special escape char.
7 Daemon abruptly closed socket.
SCRIPTING
It is very easy to use ncs_cli from /bin/sh scripts. ncs_cli reads stdin and can then also be run
in non interactive mode. This is the default if stdin is not a tty (as reported byisatty())
Here is example of invoking ncs_cli from a shell script.
#!/bin/sh ncs_cli << EOF configure set foo bar 13 set funky stuff 44 commit exit no-confirm
exit EOF
And here is en example capturing the output of ncs_cli:
#!/bin/sh { ncs_cli << EOF; configure set trap-manager t2 ip-address 10.0.0.1 port 162 snmp-
version 2 commit exit no-confirm exit EOF } | grep 'Aborted:.*not unique.*' if [ $? != 0 ]; then
echo 'test2: commit did not fail'; exit 1; fi
The above type of CLI scripting is a very efficient and easy way to test various aspects of the
CLI.
Cisco NSO CDB API
Command line utility that interfaces to common NSO library functions
Synopsis
ncs_cmd [(1) options] [filename]
ncs_cmd [(1) options] -c string
ncs_cmd -h | -h commands | -h command-name...
(1) [ -r | -o | -e | -S ] [-f [w] | [p] [ r | s ] ] [-a address] [-p port] [-u user] [-g group] [-x context]
[-s] [-m] [-h] [-d]
DESCRIPTION
The ncs_cmd utility is implemented as a wrapper around many common CDB and MAAPI
function calls. The purpose is to make it easier to prototype and test various NSO issues using
normal scripting tools.

Input is provided as a file (default stdin unless a filename is given) or as directly on the
command line using the -c string option. The ncs_cmd expects commands separated by
semicolon (;) or newlines. A pound (#) sign means that the rest of the line is treated as a
comment. For example:
ncs_cmd -c get_phase
Would print the current start-phase of NSO, and:
ncs_cmd -c "get_phase ; get_txid"
would first print the current start-phase, then the current transaction ID of CDB.
Sessions towards CDB, and transactions towards MAAPI are created as-needed. At the end of
the script any open CDB sessions are closed, and any MAAPI read/write transactions are
committed.
OPTIONS
-dDebug flag. Add more to increase debug level. All debug output will be to stderr.
-mDon't load the schemas at startup.
ENVIRONMENT VARIABLES
NCS_IPC_ADDRThe address used to connect to the NSO daemon, overrides the compiled in
default.
NCS_IPC_PORTThe port number to connect to the NSO daemon on, overrides the compiled in
default.
EXAMPLES
Getting the address of eth0
ncs_cmd -c "get /sys:sys/ifc{eth0}/ip"
Setting a leaf in CDB operational
ncs_cmd -o -c "set /sys:sys/ifc{eth0}/stat/tx 88"
Making NSO running on localhost the master, with the name node0
ncs_cmd -c "master node0"Then tell the NSO also running on localhost, but listening on port
4566, slave to the master. Calling the slave node1
ncs_cmd -p 4566 -c "slave node1 node0 127.0.0.1"
Cisco NSO Configuration Loading Utility
Command line utility to load and save NSO configurations
Synopsis
ncs_load [-W] [-S] [(1) common options] [filename]
ncs_load -l [ -m | -r | -j | -n ] [-D] [(1) common options] filename...
ncs_load -C filename...
ncs_load -h | -?
(1) [-d] [-t] [-F { x | p | j | c | i } ] [ -H | -U ] [-a] [-e] [ [-u user] [-g group...] [-c context] | [-i]]
[[-p keypath] | [-P XPath]] [-o] [-s]
DESCRIPTION
This command provides a convenient way of loading and saving all or parts of the
configuration in different formats. It can be used to initialize or restore configurations as well
as in CLI commands.
If you run ncs_load without any options it will print the current configuration in XML format
on stdout. The exit status will be zero on success and non-zero otherwise.
COMMON OPTIONS
-dDebug flag. Add more to increase debug level. All debug output will be to stderr.
-tMeasure how long the requested command takes and print the result on stderr.
-F x | p | j | c | iSelects the format of the configuration, must be set both when loading and
saving. One of XML (x), pretty XML (p) curly braces J-style CLI (j), C-style CLI (c), or I-style
CLI (i). Default is XML.
-HHide all hidden nodes. By default, no nodes are hidden unless ncs_load has attached to an
existing transaction, in which case the hidden nodes are the same as in that transaction's
session.
-UUnhide all hidden nodes. By default, no nodes are hidden unless ncs_load has attached to an
existing transaction, in which case the hidden nodes are the same as in that transaction's
session.
-u user, -g group ..., -c contextLoading and saving the configuration is done in a user session,
using these options it is possible to specify which user, groups (more than one -g can be used to
add groups), and context that should be used when starting the user session. If only a user is
supplied the user is assumed to belong to a single group with the same name as the user. This is
significant in that AAA rules will be applied for the specified user / groups / context
combination. The default is to use the system context, which implies that AAA rules will not be
applied at all.
Note
If the environment variables NCS_MAAPI_USID and NCS_MAAPI_THANDLE are set (see
the ENVIRONMENT section), or if the -i option is used, these options are silently ignored,
since ncs_load will attach to an existing transaction.
-iInstead of starting a new user session and transaction, ncs_load will try to attach to the init
session. This is only valid when NSO is in start phase 0, and will fail otherwise. It can be used
to load a “factory default”file during startup, or loading a file during upgrade.
SAVE CONFIGURATION
By default the complete current configuration will be output on stdout. To save it in a file add
the filename on the command line (the -f option is deprecated). The file is opened by
the ncs_load utility, permissions and ownership will be determined by the user
running ncs_load. Output format is specified using the -Foption.
When saving the configuration in XML format, the context of the user session (see the -
c option) will determine which namespaces with export restriction (fromncsc --export ) that are
included. If the system context is used (this is the default), all namespaces are saved, regardless
of export restriction. When saving the configuration in one of the CLI formats, the context used
for this selection is always cli.
A number of options are only applicable, or have a special meaning when saving the
configuration:

-f filenameFilename to save configuration to (option is deprecated, just give the filename on the
command line).
-WInclude leaves which are unset (set to their default value) in the output. By default these
leaves are not included in the output.
-SInclude the default value of a leaf as a comment (only works for CLI formats, not XML).
(Corresponds to the MAAPI_CONFIG_SHOW_DEFAULTS flag).
-p keypathOnly include the configuration below keypath in the output.
-P XPathFilter the configuration using the XPath expression. (Only works for the XML
format.)
-oInclude operational data in the output. (Corresponds to
the MAAPI_CONFIG_WITH_OPER flag).
LOAD CONFIGURATION
When the -l option is present ncs_load will load all the files listed on the command line . The
file(s) are expected to be in XML format unless otherwise specified using the -F flag. Note that
it is the NSO daemon that opens the file(s), it must have permission to do so. However relative
pathnames are assumed to be relative to the working directory of the ncs_load command .
If neither of the -m and -r options are given when multiple files are listed on the command
line, ncs_load will silently treat the second and subsequent files as if -m had been given, i.e. it
will merge in the contents of these files instead of deleting and replacing the configuration for
each file. Note, we almost always want the merge behavior. If no file is given, ncs_load will
stream standard input to NSO.
-f filenameThe file to load (deprecated, just list the file after the options instead).
-mMerge in the contents of filename, the (somewhat unfortunate) default is to delete and
replace.
-jDo not run FASTMAP, if FASTMAPPED service data is loaded, we sometimes do not want
to run the mapper code. One example is a backup saved in XML format that contains both
device data and also service data.
-nOnly load data to CDB inside NSO, do not attempt to perform any update operations towards
the managed devices. This corresponds to the 'no-networking' flag to the commit command in
the NSO CLI.
-xLax loading. Only applies to XML loading. Ignore unknown namespaces, attributes and
elements.
-rReplace the part of the configuration that is present in filename, the default is to delete and
replace. (Corresponds to the MAAPI_CONFIG_REPLACE flag).
-aWhen loading configuration in 'i' or 'c' format, do a commit operation after each line. Default
and recommended is to only commit when all the configuration has been loaded. (Corresponds
to the MAAPI_CONFIG_AUTOCOMMIT flag).
-eWhen loading configuration do not abort when encountering errors (corresponds to
the MAAPI_CONFIG_CONTINUE_ON_ERROR flag).
-DDelete entire config before loading.
-p keypathDelete everything below keypath before loading the file.
-oAccept but ignore contents in the file which is operational data (without this flag it will be an
error).
LOAD CDB OPERATIONAL
The -C option is used to load operational data. When you use -C all other options (except -d)
are ignored, since they don't apply. Files on the command line must be in XML format
Any data in the file which isn't part of CDB operational per the data model will be ignored.
This means that you can save a single file with both configuration and operational data and feed
it back to ncs_load.
If you use a relative path for filename it is assumed to be relative to the working directory of
the ncs_load command
EXAMPLES
Example 1. Reloading all xml files in the cdb directory
ncs_load -D -m -l cdb/*.xml
Example 2. Merging in the contents of conf.cli

ncs_load -l -m -F j conf.cli
Example 3. Print interface config and statistics data in cli format

ncs_load -F i -o -p /sys:sys/ifc
Example 4. Using xslt to format output

ncs_load -F x -p /sys:sys/ifc | xsltproc fmtifc.xsl -
Example 5. Using xmllint to pretty print the xml output

ncs_load -F x | xmllint --format -
Example 6. Saving config and operational data to /tmp/conf.xml

ncs_load -F x -o > /tmp/conf.xml
Example 7. Restoring both config and operational data

ncs_load -l -F x -o /tmp/conf.xml ncs_load -C /tmp/conf.xml
Example 8. Measure how long it takes to fetch config

ncs_load -t > /dev/null elapsed time: 0.011 s
Example 9. Output all instances in list /foo/table which has ix larger than 10
ncs_load -F x -P "/foo/table[ix > 10]"
ENVIRONMENT
NCS_IPC_ADDRThe address used to connect to the NSO daemon, overrides the compiled in
default.
NCS_IPC_PORTThe port number to connect to the NSO daemon on, overrides the compiled in
default.

NCS_MAAPI_USID, NCS_MAAPI_THANDLEIf set ncs_load will attach to an existing
transaction in an existing user session instead of starting a new session.
These environment variables are set by the NSO CLI when it invokes external commands,
which means you can run ncs_load directly from the CLI. For example, the following addition
to the <operationalMode> in a clispec file (see clispec(5))
<cmd name="servers" mount="show"> <info/> <help/> <callback> <exec>
<osCommand>ncs_load</osCommand> <args>-F j -p /system/servers</args> </exec>
</callback> </cmd>
will add a show servers command which, when run will invoke ncs_load -F j -p
/system/servers. This will output the configuration below/system/servers in curly braces
format.
Note that when these environment variables are set, it means that the configuration will be
loaded into the current CLI transaction (which must be in configure mode, and have AAA
permissions to actually modify the config). To load (or save) a file in a separate transaction,
unset these two environment variables before invoking the ncs_load command.
Cisco NSO CLI Script Example
cisco@nso:~$ more l3mplsvpn.sh
#!/bin/sh
{ ncs_cli << EOF;
configure
set services l3mplsvpn $1 vpn-name $2 customer $3 link $4 device $5 interface $6 routing-
protocol bgp
commit
exit no-confirm
exit
EOF
}
if [ $? != 0 ]; then echo 'l3mplsvpn.sh: really serious error'; exit 1; fi
cisco@nso:~$ l3mplsvpn.sh 10002 VPN5 ACME 4 PE31 4

Commit complete. Return processing:
No modifications to commit.  Exit code for system issues
syntax error: "102" is out of range.  Text output for command issues
 Sample script executing a command and capturing the output

The figure illustrates a simple script used to provision a link in a Layer-3 Multiprotocol Label Switching
Virtual Private Network (MPLS VPN) service which we have created in the previous lesson. The script will
provide textual feedback from which we can determine whether the action was successful or not.
The ncs_cli command can be used in a variety of manners when other integration options are not possible:
 Scripting to automate tasks.
 Integration with a web application using common gateway interface (CGI).
Perl script example:

#!/usr/bin/perl
if ($#ARGV<5){
print "\nl3mplsvpn.pl vpnid vpnname customer linkid device
interface\n\n";
exit;
}
my $cmd=qq|ncs_cli << EOF;

configure
set services l3mplsvpn $ARGV[0] vpn-name $ARGV[1] customer
$ARGV[2] link $ARGV[3] device $ARGV[4] interface $ARGV[5]
routing-protocol bgp
commit
EOF
|;
print "EXECUTING:\n$cmd";
$l=`$cmd`;
print "\nRESULT:\n$l";

Cisco NSO Web Integration
In this topic you will learn how to make use of the REST API to manage configurations in
NSO.
Cisco NSO Web Integration

Integration with
Use cases: existing WebUI
 Integrate with existing EMS / NSM systems EMS / NMS / Web Portal
 Integrate with existing web-based management

portals Web Server
APIs: JavaScript
REST API
(JSON/RPC)
 JSON RPC for more complex integration
Data
requiring maintenance of session state JSON XML Format
 REST for simple single transactions MAAPI
CDB
REST example using curl and a GET request:
curl -u admin:admin http://localhost:8080/api/running/devices/device/PE13/config/router?deep&select=bgp;ospf
NSO provides the JavaScript JSON RPC API and the REST API that can be used in front-end systems for
WebUI integration purposes.
When integrating the NSO WebUI with other systems it is important to remember that the NSO WebUI is
dynamically adapting to the data models. That means that the interface is not static and any changes in the
data model may affect the integration with front-end systems.
The JSON RPC is recommended for a more complex integration scenario which wants to make use of the
session state and active interaction between the front-end system and NSO. The REST API can be used in
more simplistic environment where simple stateless web transaction support is needed.
REST API
The RESTful API over HTTP can be used for accessing data defined in YANG, using the datastores defined
in NETCONF.
Configuration data and state data are exposed as resources that accept the GET method. Resources
representing configuration data also accept the DELETE, PATCH, POST, and PUT methods:
 GET to retrieve a resource.
 PUT to replace a resource.
 POST to create a resource.
 DELETE to delete a resource.
There is also a number of query options that allow the filtering of returned data. For example:
 select=resource1;resource2(expression): semicolon separated list of resources and/or expression
within parenthesis
 deep: display entire subtree
 shallow: only display resource without subtree
 offset: display a limited set of list entries to retrieve
 limit: display a limited set of list entries to retrieve
In order to enable Representation State Transfer (REST), in NSO, REST must be enabled in ncs.conf. The
webserver configuration for REST is shared with the WebUI's config. However, the WebUI does not have to
be enabled for REST to work.
Example:
curl -u admin:admin
http://localhost:8080/api/running/devices/device/PE13/config/router?deep&select=bgp;ospf

Cisco NSO REST API Example
cisco@nso:~$ curl -u admin:admin
http://localhost:8080/api/running/devices/device/PE11/config/ios:router/bgp?deep
<collection xmlns:y="http://tail-f.com/ns/rest">
<bgp>
<as-no>1</as-no> Use prefixes where Use deep to display
<bgp>
<bestpath>
needed all child elements
</bestpath>
<log-neighbor-changes/>
<nexthop> HTTP methods:
</nexthop>
</bgp>
 GET to retrieve resources
<distance>  PUT to replace resources
</distance>
<neighbor>  POST to create resources
<id>10.0.0.101</id>  DELETE to delete resources
</neighbor>
...
 XML encoded data received or sent by default

The example illustrates the usage of REST API by using the curl shell command. In the example, we access
the configuration of Border Gateway Protocol (BGP) on router PE13. Note the similarity with NSO CLI in
the path used and the output produced:
 NSO CLI: show devices device PE11 config ios:router bgp | display xml
 REST: /api/running/devices/device/PE11/config/router/bgp?deep
Cisco NSO REST API Example
cisco@nso:~$ curl -u admin:admin -H "Accept: application/vnd.yang.data+json"
http://localhost:8080/api/running/devices/device/PE11/config/ios:router/bgp?deep
{
"tailf-ned-cisco-ios:router": {
"bgp": [
{
"as-no": 1,
"address-family": {
"ipv4": [
Instruct NSO to reply Depth options:
{
"af": "unicast", using JSON for data - Default: 5 levels
"bgp-af": {
"bgp": {
"bestpath": {
encoding - "deep": all levels
}, - "shallow": 2 levels
"nexthop": {
}
}
},
"neighbor": [
{
"id": "10.1.1.13",
"remote-as": "1",
"capability": {
},
"translate-update": {
}
},
...
 JSON can be used instead of XML if desired

Northbound application platform or developer may prefer JSON data encoding which may be achieved using
the Accept and Content-Type HTTP options in order to receive or supply data in JSON format.

Cisco NSO Plugin Scripts
In this topic you will learn how to add new commands to the NSO CLI by using shell scripts.
Cisco NSO Plugin Scripts
Use cases:
 Augment the NSO CLI Custom
 Augment policy rules commands
 Trigger external events upon

configuration change
Execute upon CLI
commit Policy
Scripts validation
CDB
With the scripting mechanism it is possible for an end-user to add new functionality to Cisco NSO CLI in a
plug-and-play like manner without any special tools. There are three categories of scripts:
 command scripts are used to add new commands to the CLI.
 policy scripts are invoked at validation time and may control the outcome of a transaction. Policy
scripts have the mandate to cause a transaction to abort.
 post-commit scripts are invoked when a transaction has been committed. Post-commit scripts can for
example be used for logging, sending external events etc.
 Scripts are located in the scripts subdirectory where there are three additional subdirectories, one for
each category of scripts (command, policy, and post-commit). Scripts are automatically loaded at startup
and may also be manually reloaded with the CLI command script reload.
The scripts can make use of other APIs available to process operational or configuration data:
 ncs-maapi
 netconf-console
 ncs_cli
 ncs_cmd
 ncs_load
Cisco NSO MAAPI
Name
ncs-maapi — command to access an ongoing transaction
Synopsis
ncs-maapi --get Path...
ncs-maapi --set Path Value [ Path Value... ]
ncs-maapi --keys Path...
ncs-maapi --exists Path...
ncs-maapi --delete Path...
ncs-maapi --create Path...
ncs-maapi --insert Path...
ncs-maapi --revert
ncs-maapi --msg To Message Sender
--priomsg To Message
--sysmsg To Message
ncs-maapi --cliget Param...
ncs-maapi --cliset Param Value [ Param Value... ]
ncs-maapi --cmd2path Cmd [ Cmd ]
ncs-maapi --cmd-path [--is-deleta ] [--emit-parents ] [--non-recursive ] Path [ Path ]
ncs-maapi --cmd-diff Path [ Path ]
ncs-maapi --keypath-diff Path
ncs-maapi --clicmd [--get-io ] [--no-hidden ] [--no-error ] [--no-aaa ] [--no-fullpath ] [-
unhide <group>] Cli command...
DESCRIPTION
This command is intended to be used from inside a CLI command or a NETCONF extension
RPC. These can be implemented in several ways, as an action callback or as an executable.
It is sometimes convenient to use a shell script to implement a CLI command and then invoke
the script as an executable from the CLI. The ncs-maapi program makes it possible to
manipulate the transaction in which the script was invoked.
Using the ncs-maapi command it is possible to, for example, write configuration wizards and
custom show commands.
Use the man ncs-maapi command to get the complete description of the command options and
examples.

Cisco NSO Plugin Script Example: Command Script
cisco@nso:~$ more showallintfs.pl
#!/usr/bin/perl
 Any scripting language can be used
while (my $c = shift(@ARGV)){
if ($c=~/^--command$/i){ writesyntax(); }  --command argument tells NSO about
}
the syntax and parameters
sub writesyntax{
print q|
 cmdpath option tells NSO about the
begin command CLI command
modes: oper config
styles: c j
cmdpath: show interfaces brief
help: This command displays all interfaces on all devices.
end
|;
exit;
}
my $l=`ncs-maapi --clicmd "show configuration devices device * config ios:interface | display xpath |
nomore" 2>&1`;
print $l;
All scripts are required to provide a formal description of their interface. When the scripts are loaded, NSO
will invoke the scripts with --command, --policy or --post-commit as an argument.
The script must respond by writing its formal interface description on stdout and exit normally. Such a
description consists of one or more sections. The required sections depend on the category of the script.
In the example, we use the ncs-maapi command to execute a native NSO CLI command. The example is
effectively creating and alias for the CLI command. Note that you may achieve a similar goal by adding a
new command to the ncs.cli (this approach however requires the recompiling of the CLI and restarting of the
server).
Note You should use a different API if you want to process the output of a command (ncs-maapi is executed
with the context of the NSO CLI and does not allow the processing of output; you should use ncs_cli or
netconf-console instead; described earlier in this lesson).
Command Script Example

The following script provides an echo command in the CLI where it can be used to display a string or store a
string in a file.
#!/bin/sh
set -e
usage=
newline=cat
file=
while [ $# -gt 0 ]; do
case "$1" in
--h)
usage=1
;;
--command)
# Configuration of the command
#
# modes - CLI mode (oper config)
# styles - CLI style (c i j)
# cmdpath - Full CLI command path
# help - Command help text
#
# Configuration of the parameters
#
# name - (optional) name of the parameter
# presence - optional or mandatory
# type - void - A parameter without a value
# words - any - Multi word param. Only valid for
the last param
# flag - Extra word added before the parameter
value
# prefix - Extra string prepended to the parameter
value
# help - Command help text
cat << EOF
begin command
modes: oper
styles: c i j
cmdpath: my scripting echo
help: Display a line of text
end
begin param
name: nolf
type: void
presence: optional
flag: -n
help: Do not output the trailing newline
end
begin param
name: file
presence: optional
flag: -f
help: Redirect output to file
end
begin param
presence: mandatory
words: any
help: String to be displayed
end
EOF
exit
;;

-n)
# Disable output of newline
newline="tr -d '\012'"
;;
-f)
# Redirect output to file
if [ $# -lt 2 ]; then
echo "Too few arguments"
usage=1
else
file=$2
shift
fi
;;
*)
break
;;
esac
shift
done
# String to be displayed.
string=$*
if [ x"$usage" != x ]; then
echo
echo "Usage: $0 [-n] [-f file] string"
echo
echo " --command Mandatory for command scripts"
echo " --params Mandatory for command scripts"
echo
echo " -h Display this help and exit"
echo " -n Do not output trailing newline"
echo " -f filename Redirect output to file"
echo " string String to be displayed"
exit 1
fi
if [ "x$file" = "x" ]; then

/bin/echo "$string" | $newline
else
/bin/echo "$string" | $newline > $file
fi
Post-Commit Script Example

The following script is executed every time a commit is performed and logs the configuration changes to a
new transaction log file.
#!/bin/sh
set -e
if [ $# -gt 0 ]; then
case "$1" in
--post-commit)
cat << EOF
begin post-commit
end
EOF
exit 0
;;
*)
echo
echo "Usage: $0 [--post-commit]"
echo
echo " --post-commit Mandatory for post-commit
scripts"
exit 1
;;
esac
else
file='/var/log/ncs/ncs-transaction.log';
# echo "Redirect stdout to logfile"
exec > "${file}" 2>&1
echo
date
echo $0
echo "CONFD_MAAPI_USID=$CONFD_MAAPI_USID"
echo "CONFD_MAAPI_THANDLE=$CONFD_MAAPI_THANDLE"
echo
echo "--- transaction diff ---"
ncs-maapi --keypath-diff /
fi

Cisco NSO SNMP
In this topic you will learn how to use SNMP in the northbound direction.
Cisco NSO SNMP

 Used to monitor the NSO system and alarms generated by it
 By default, the NSO SNMP agent listens on UDP port 4000
 NSO-specific MIBs are located in the $NCS_DIR/src/ncs/snmp/mibs directory
snmp agent enabled

snmp agent ip 0.0.0.0
snmp agent udp-port 4000
snmp agent version v1
snmp agent version v2c
snmp agent version v3
snmp agent engine-id enterprise-number 32473
snmp agent engine-id from-text testing
snmp agent max-message-size 50000
snmp system contact "Joe Admin"
snmp system name "NSO"
snmp system location "HQ"
The Cisco NSO SNMP agent provides SNMP access to the data available through the NSO management
backplane. The same data can also be accessed via other protocols/applications such as NETCONF, WebUI,
and CLI. This data can be stored in CDB, or made available by a data provider.
SNMP Example
cisco@nso:~$ snmpwalk -M /opt/ncs/ncs-3.2/src/ncs/snmp/mibs -m ALL -v 2c -c public 127.0.0.1:4000 TAILF-
TOP-MIB::tfModules
TAILF-ALARM-MIB::tfAlarmNumber.0 = Gauge32: 22
TAILF-ALARM-MIB::tfAlarmLastChanged.0 = STRING: 2014-11-8,9:33:24.4,+0:0
TAILF-ALARM-MIB::tfAlarmType.1 = STRING: connection-failure
TAILF-ALARM-MIB::tfAlarmType.14 = STRING: package-load-failure
...
 The net-snmp tools used to test SNMP agent capabilities
Cisco NSO supports SNMP to monitor the system status and the Cisco NSO alarms. The TAILF-ALARM-
MIB MIB is available in src/ncs/snmp/mibs subdirectory.

Summary
 Use NETCONF for integration with other OSS/NMS systems if possible
 Use CLI for scripted local task automation
 Use plugin scripts to augment the NSO CLI with custom commands
 Use SNMP to monitor Cisco NSO system and alarms
References
 Cisco NSO documentation
Lesson 4-2
Cisco NSO System

Administration
Overview
This lesson describes some of the more common administrative task relating to the Cisco
Network Services Orchestrator system with the aim of providing a reliable and powerful
orchestration solution.
Objectives
 Describe the most common Cisco NSO administration tasks
 System Configuration
 System Maintenance
 Authentication and Authorization
 Clustering
 High Availability
 Scalable System Management
 System Troubleshooting
System Configuration
In this topic you will learn how to configure the Cisco NSO system using the configuration file
and the inline configuration options of the Cisco NSO CLI.
System Configuration and Installation Type

 NSO has two installation types that influence system administration:
 Local installation: should be used development, testing and similar
environments
 System installation: used in a final production environment
 Understand the implications of installation types when managing the
system:
 Location of files and directories
 Availability of certain features
Remember that there are two main options when installing the NSO system:
 Local installation: this installation creates a sand-boxed environment where there are all the files and
directories needed for the NSO system top operate.
 System installation: this installation integrates into the architecture of the hosting operation system so
you will find that various parts of the file system are used for NSO.
Either installation can however be tuned to use arbitrary directories for various purposes.
It is important to know the type of installation in order to be able to manage the system.
System Configuration
 Primary source of system configuration is the ncs.conf file:
 In system installation the default location is /etc/ncs/ncs.conf
 In local installation the ncs.conf file is located in the running directory of NSO
System installation example: Edit the configuration

cisco@nso:~$ cd /etc/ncs
cisco@nso:/etc/ncs$ sudo vim ncs.conf
Tell NSO to reload the
...
configuration
cisco@nso:/etc/ncs$ ncs --reload
 All other system configuration is stored within NSO's CDB (i.e. accessible via
CLI or WebUI)
Cisco NSO is configured in two different ways. It's configuration file, ncs.conf, and also through whatever
data that is entered into Cisco NSO itself. For example, if we instruct Cisco NSO to manage yet another
device, i.e. we add an entry to /devices/device, which could certainly be considered as configuration data for
Cisco NSO itself.
The ncs.conf file contains the core configuration describing the startup options and the main system
components. Everything else is configured through the NSO itself via the CLI or WebUI.

System Configuration: ncs.conf
<ncs-config xmlns="http://tail-f.com/yang/tailf-ncs-config">
 Environment variables: <load-path>
 NCS_DIR: installation location (e.g. <dir>${NCS_RUN_DIR}/packages</dir>
<dir>${NCS_DIR}/etc/ncs</dir>
/opt/ncs/current)
<dir>${NCS_DIR}/etc/ncs/snmp</dir>
 NCS_RUN_DIR: running location (e.g. </load-path>
/var/opt/ncs)

 load-path: locate *.fxs files <scripts>
<dir>${NCS_RUN_DIR}/scripts</dir>
 scripts: locate plugin scripts <dir>${NCS_DIR}/scripts</dir>
</scripts>
 state-dir: installed packages <state-dir>${NCS_RUN_DIR}/state</state-dir>
 notifications: northbound notifications <notifications>…</notifications>

on alarms <cdb>
<db-dir>${NCS_RUN_DIR}/cdb</db-dir>
 cdb: CDB location and initiation 
<init-path>
<dir>${NCS_DIR}/var/ncs/cdb</dir>
</init-path>
</cdb>
The directory parameters are dynamically generated based on the environment variables passed to the NSO
server at startup:
 The $NCS_DIR environment variable contains the installation directory of Cisco NSO, such as
/opt/ncs/current.
 The $NCS_RUN_DIR environment variable contains the running directory of Cisco NSO, such as
/var/opt/ncs.
 The $NCS_LOG_DIR environment variable contains the log file directory for Cisco NSO, such as
/var/log/ncs.
The ncs.con XML file contains the following main sections and confirms to the YANG model defined in
tailf-ncs-config.yang:
 The load-path element configures the locations where the systems is to search for *.fxs files.
 The scripts element configures the locations where the plug-and-play scripts are located.
 The state-dir element configures the location where the running packages are located.
 The notification element configures the notification mechanisms for alarms.
 The cdb element configures the location of the Configuration Database (CDB) files and from where they
are initiated.
 (list continued on the next page)
System Configuration: ncs.conf (Cont.)
<logs>
 Environment variables: <syslog-config> … </syslog-config>
 NCS_LOG_DIR: log file location (e.g. <ncs-log>
/var/logs/ncs) <enabled>true</enabled>
<file>
 logs: location and configuration of <name>${NCS_LOG_DIR}/ncs.log</name>
<enabled>true</enabled>
logging: </file>
 syslog: disabled <syslog>
 ncs-log: enabled </syslog>
 developer: enabled </ncs-log>
<developer-log> … </developer-log>
 audit: enabled <developer-log-level>info</developer-log-level>
 netconf: enabled <audit-log> … </audit-log>
<netconf-log> … </netconf-log>
 snmp: enabled <snmp-log> … </snmp-log>
 webui-browser-log: enabled <webui-browser-log> … </webui-browser-log>
<webui-access-log> … </webui-access-log>
 webui-access-log: enabled <xpath-trace-log> … </xpath-trace-log>
 xpath-trace-log: disabled (useful for <error-log> … </error-log>
troubleshooting XPath, CPU intensive) </logs>
 error-log: enabled
 (continued from the previous page)

 The log element configures a number of logging options which can be tuned to fit a development or a
production environment:
— syslog-config: forwarding of log messages to a Syslog server (disabled by default).
— ncs-log: configures the location of NSO log files and whether they should be forwarded to the
Syslog service (both enabled by default).
— developer-log: configures the usage of the devel.log file where detailed actions are logged that
can be useful for the application development (enabled by default).
— audit-log: configures the usage of the devel.log file where all administrative actions performed
via CLI, WebUI or any application programming interface (API) are logged (enabled by
default).
— netconf-log: enabled by default).
— snmp-log: contains a trace of all events in the Simple Network Management Protocol (SNMP)
agent (enabled by default).
— webui-browser-log: makes it possible to log JavaScript errors and exceptions in a log file on the
target device instead of just in the browser's error console. (enabled by default).
— webui-access-log: is an access log for the embedded NSO web server (enabled by default).
— xpath-trace-log: disabled by default). This feature is useful for the troubleshooting of XPath in
YANG must statements but it is CPU intensive so it should not be used in a production
environment.
— error-log: contains detailed logs useful when suspecting a software issue (enabled by default).

<aaa> … </aaa>
 aaa: authentication and authorization
configuration: <rollback>
 PAM (enabled) <directory>${NCS_RUN_DIR}/rollbacks</directory>
 Local (enabled) <history-size>500</history-size>
</rollback>
 External (disabled)
<cli>
 rollback: configuration history <enabled>true</enabled>
<ssh>
 cli: NSO CLI configuration: <enabled>true</enabled>
<ip>0.0.0.0</ip>
 SSH configuration <port>2024</port>
 Cisco and Juniper CLI style prompts </ssh>
<prompt1>\u@ncs> </prompt1>
<prompt2>\u@ncs% </prompt2>
<c-prompt1>\u@ncs# </c-prompt1>
<c-prompt2>\u@ncs(\m)# </c-prompt2>
…
</cli>

 The aaa element configures the basis for Authentication, Authorization and Accounting (AAA),
discussed later in more detail.
 The rollback element configures the location and parameters for NSO configuration rollback files.
 The cli element configures the Cisco NSO CLI access parameters and prompts.
<webui> … </webui>
 webui: web-based user interface:
 HTTP (e.g. port 8080, enabled) <rest>
 SSL configuration (e.g. port 8888, private </rest>
key, certificate, disabled)
<netconf-north-bound>
 rest: REST API (enabled) <enabled>true</enabled>
 netconf: northbound NETCONF <transport>

<ssh>
configuration <enabled>true</enabled>
 SSH: NETCONF over SSH (enabled) <ip>0.0.0.0</ip>
<port>2022</port>
 TCP: NETCONF over raw TCP (enabled) </ssh>
<tcp>
<ip>127.0.0.1</ip>
<port>2023</port>
</tcp>
</transport>
</netconf-north-bound>

 The webui element configures the Cisco NSO WebUI access parameters.
 The rest element configures the availability of Representation State Transfer (REST) API.
 The webui element configures the northbound Network Configuration Protocol (NETCONF)
availability and access parameters.

System Maintenance
In this topic you will learn about common Cisco NSO system maintenance options.
System Maintenance
 Backup
 Restore Manual:
 backup
Scheduled
 Upgrade  restore
backup
 upgrade
Cisco NSO Remote backup
Note! These features are only applicable to the system installation
This topic covers the most important system maintenance tasks:

 System backup: backing up of all the important files that describe the state of the system.
 System restore: the procedure to restore from the last backed up state in case of a failure of the system.
 System upgrade: the procedure to upgrade the Cisco NSO software to a new version.
The backup procedure can be scheduled to run on regular basis as well as being run manually. The restore
and upgrade procedures are rare and are always manual.
Cisco NSO can be backed up using the ncs-backup command which backs up the database (CDB) files, state
files, config files and rollback files from the installation directory. Use the ncs-backup command to take a
complete backup (for disaster recovery).
The backup will be stored in the Run Directory /var/opt/ncs/backups/ncsVERSION@DATETIME.backup.
Make sure that the backup files are also properly backed up to another system to mitigate possible disk
failures in the Cisco NSO server which would result in the loss of the system and the backup files.
NAME
ncs-backup - Command to backup and restore NSO data
SYNOPSIS
ncs-backup [--install-dir InstallDir] [--non-interactive]
ncs-backup --restore [Backup] [--install-dir InstallDir] [--non-interactive]
DESCRIPTION
The ncs-backup command can be used to backup and restore NSO CDB, state data, and config files for an
NSO "system installation", i.e. one that was done with the --system-install option to the NSO installer (see
ncs-installer(1)). Unless the --restore option is used, the command creates a backup. The backup is stored in
the RunDir/backups directory, named with the NSO version and current date and time.
OPTIONS
--restore [ Backup ]
Restore a previously created backup. The Backup argument is either the name of a file in the
RunDir/backups directory or the full path to a backup file. If the argument is omitted, unless the

--non-interactive option is given, the command will offer selection from available backups.
[ --install-dir InstallDir ]
Specifies the directory for installation of NSO static files, like the --install-dir option to the installer. If this
option is omitted, /opt/ncs will be used for InstallDir.
[ --non-interactive ]
If this option is used, restore will proceed without asking for confirmation.
Cisco NSO restore is performed if you would like to switch back to a previous good state or restore a backup.
Note It is always advisable to stop NSO before performing the restore operation.

System Upgrade
root@nso:~# sh ncs-NEWVERSION.OS.ARCH.installer.bin --system-install
...
root@nso:~# /etc/init.d/ncs stop
Stopping ncs: .
root@nso:~# ncs-backup
INFO Backup /var/opt/ncs/backups/ncs-4.1.1@2016-01-22T20:01:10.backup created successfully
root@nso:~# cd /opt/ncs
root@nso:~# rm -f current
root@nso:~# ln -s ncs-4.1.1 current
root@nso:~# NCS_RELOAD_PACKAGES=true /etc/init.d/ncs start
Starting ncs: .
root@nso:~#
 Install the new version

 Stop the server and create a backup
 Switch to the new version by modifying symbolic links
 Start the new server version by also reloading packages (make sure the packages are available to the new
version)
 Verify that the server has installed properly
Follow these steps to upgrade Cisco NSO to a new version (the figure above illustrates an upgrade from
version 3.2 to version 3.3):
Step 1 Install the new version.
sudo sh ncs-NEWVERSION.OS.ARCH.installer.bin --system-install
Step 2 Stop previous installed NSO.
/etc/init.d/ncs stop
Step 3 Take a complete backup (for disaster recovery)
ncs-backup
Step 4 Switch to new version by updating symbolic link.
cd /opt/ncs
rm -f current
ln -s ncs-NEWVERSION current
Step 5 Make sure that the /var/opt/ncs/packages directory has packages that are appropriate for the new
version. When upgrading from one version of NSO to another version in the same major branch
i.e x.y are unchanged in NCS-x.y.z (Ex: ncs-3.1 to ncs-3.1.2), it should be possible to continue to
use the same packages. But when upgrading to a different major branch, the packages normally
need to be rebuilt (or pre-built packages for the new major branch need to be used).
Step 6 Start NSO with package reload option.
NCS_RELOAD_PACKAGES=true /etc/init.d/ncs start
Step 7 Verify that everything is working.
Step 8 If you want to switch back to previous known/good state, start by stopping NSO.
/etc/init.d/ncs stop
— Then restore from backup.
ncs-backup --restore
— Move back symbolic link
cd /opt/ncs
rm -f current
ln -s ncs-VERSION current
— And restart NSO.
/etc/init.d/ncs start

Authentication and Authorization
In this topic you will learn about authentication and authorization options in Cisco NSO.
Authentication and Authorization
 Authentication: verification of Login (e.g. NETCONF)

identity
 Authorization: verification of
privileges
 Command authorization
RADIUS
 Data access authorization LDAP
PAM
Login (e.g. CLI,
 NACM is used to implement access WebUI)
control (RFC 6536)
Cisco NSO AAA Server
This topic describes how to use Cisco NSO's built-in authentication and authorization mechanisms. Users log
into NSO through the CLI, NETCONF, SNMP, or via the WebUI. In either case, users need to be
authenticated. That is, a user needs to present credentials, such as a password or a public key in order to gain
access.
Once a user is authenticated, all operations performed by that user need to be authorized. That is, certain
users may be allowed to perform certain tasks, whereas others are not. This is called authorization. We
differentiate between authorization of commands and authorization of data access.
The NSO daemon manages device configuration including AAA information. In fact, NSO both manages
AAA information and uses it. The AAA information describes which users may login, what passwords they
have and what they are allowed to do.
This is solved in NSO by requiring a data model to be both loaded and populated with data. As delivered,
NSO uses the YANG module tailf-aaa.yang for authentication, while ietf-netconf-acm.yang (NETCONF
Access Control Model [NACM], RFC 6536) as augmented by tailf-acm.yang is used for group assignment
and authorization.
Authentication Configuration: ncs.conf
<aaa>
 local-authentication: users <ssh-server-key-dir>${NCS_CONFIG_DIR}/ssh</ssh-server-key-dir>
stored in CDB: <pam>
 Static passwords <service>common-auth</service>
 Public-key authentication </pam>
<external-authentication>
(RSA, DSA)
<enabled>false</enabled>
<executable>my-test-auth.sh</executable>
 pam (recommended): </external-authentication>
users authenticated
through PAM which can <local-authentication>
offload authentication to a <enabled>true</enabled>
</local-authentication>
central AAA server (e.g. to </aaa>
use one-time password
authentication)
 external-authentication: users are authenticated using an external executable
AAA related items in ncs.conf

NSO itself is configured through a configuration file - ncs.conf. In that file we have the following items
related to authentication and authorization:
 /ncs-config/aaa/sshserver-key-dir
If Secure Shell (SSH) termination is enabled for NETCONF or the CLI, the NSO built-in SSH server needs
to have server keys. These keys are generated by the NSO install script and by default end up in
$NCS_DIR/etc/ncs/ssh. It is also possible to use OpenSSH to terminate NETCONF or the CLI. If OpenSSH
is used to terminate SSH traffic, the SSH keys are not necessary.
 /ncs-config/aaa/ssh-pubkey-authentication
If SSH termination is enabled for NETCONF or the CLI, this item controls how the NSO SSH daemon
locates the user keys for public key authentication. See Section 35.4.1, “Public Key Login”
 /ncs-config/aaa/local-authentication/enabled
The term "local user" refers to a user stored under /aaa/authentication/users. The alternative is a user
unknown to NSO, typically authenticated by Pluggable Authentication Modules (PAM). By default, NSO
first checks local users before trying PAM or external authentication. Local authentication is practical in test
environments. It is also useful when we want to have one set of users that are allowed to login to the host
with normal shell access and another set of users that are only allowed to access the system using the normal
encrypted, fully authenticated, northbound interfaces of NSO.
If we always authenticate users through PAM it may make sense to set this configurable to false. If we
disable local authentication it implicitly means that we must use either PAM authentication or "external
authentication". It also means that we can leave the entire data trees under /aaa/authentication/users and, in
the case of "external auth" also /nacm/groups (for NACM) or /aaa/authentication/groups (for legacy tailf-aaa)
empty.
 /ncs-config/aaa/pam

NSO can authenticate users using PAM. PAM is an integral part of most Unix-like systems. PAM is a
complicated - albeit powerful - subsystem. It may be easier to have all users stored locally on the host,
However if the AAA infrastructure we want to store users in a central location, PAM can be used to access
the remote information. PAM can be configured to perform most login scenarios including RADIUS and
Lightweight Directory Access Protocol (LDAP). One major drawback with PAM authentication is that there
is no easy way to extract the group information from PAM. PAM authenticates users, it does not also assign
a user to a set of groups.
 /ncs-config/aaa/default-group
If this configuration parameter is defined and if the group of a user cannot be determined, a logged in user
ends up in the given default group.
 /ncs-config/aaa/external-authentication
NSO can authenticate users using an external executable.
Password Login
Password login is triggered in the following cases:
 When a user logs in over NETCONF or the CLI using the built in SSH server, with a password. The
user presents a username and a password in accordance with the SSH protocol.
 When a user logs in using the WebUI. The WebUI asks for a username and password.
 When the method Maapi.authenticate() is used.
In this case, NSO will by default try local authentication, PAM, and external authentication, in that order, as
described below. It is possible to change the order in which these are tried, by modifying the ncs.conf.
parameter /ncs-config/aaa/auth-order.
1. If /aaa/authentication/users/user{$USER} exists and the presented password matches the encrypted
password in /aaa/authentication/users/user{$USER}/password the user is authenticated.
2. If the password does not match or if the user does not exist in /aaa/authentication/users, PAM login is
attempted, if enabled. See Section 35.4.3, “PAM” for details.
3. If all of the above fails and external authentication is enabled, the configured executable is invoked.
Public Key Login

When a user logs in over NETCONF or the CLI using the built-in SSH server, with public key login, the
procedure is as follows. The user presents a username in accordance with the SSH protocol. The SSH server
consults the settings for /ncs-config/aaa/ssh-pubkey-authentication and /ncs-config/aaa/local-
authentication/enabled:
1. If ssh-pubkey-authentication is set to local, and the SSH keys in
/aaa/authentication/users/user{$USER}/ssh_keydir match the keys presented by the user, authentication
succeeds.
2. Otherwise, if ssh-pubkey-authentication is set to system, local-authentication is enabled, and the SSH
keys in /aaa/authentication/users/user{$USER}/ssh_keydir match the keys presented by the user,
authentication succeeds.
3. Otherwise, if ssh-pubkey-authentication is set to system and the user
/aaa/authentication/users/user{$USER} does not exist, but the user does exist in the OS password
database, the keys in the user's $HOME/.ssh directory are checked. If these keys match the keys
presented by the user, authentication succeeds.
4. Otherwise, authentication fails. In all cases the keys are expected to be stored in a file called
authorized_keys (or authorized_keys2 if authorized_keys does not exist), and in the native OpenSSH
format (i.e. as generated by the OpenSSH ssh-keygen command). If authentication succeeds, the user's
group membership is established as described in Section 35.6, “Group Membership”.
This is exactly the same procedure that is used by the OpenSSH server with the exception that the built-in
SSH server also may locate the directory containing the public keys for a specific user by consulting the
/aaa/authentication/users tree.

High Availability
In this topic you will learn about the high availability functionality available with Cisco NSO.
High Availability
 High Availability Framework (HAFW) is Northbound Read / write

used to controls master/slave state APIs CDB
 NSOs only replicate CDB state

 Writing to CDB is only possible on the
Replicate CDB
master
 Load balancers can be used to provide
seamless access to active node (master) Cisco NSO Cisco NSO
Master / Active Slave / Standby
Cisco NSO support replication of the CDB configuration as well as of the operational data kept in CDB. The
replication architecture is that of one active master and a number of passive slaves.
A group of NSO hosts consisting of a master, and one or more slaves, is referred to as a high availability
group (and sometimes as an availability group cluster - however this is completely independent and separate
from the clustering feature).
All configuration write operations must occur at the master and NSO will automatically distribute the
configuration updates to the set of live slaves. Operational data in CDB may be replicated or not based on the
tailf:persistent statement in the data model. All write operations for replicated operational data must also
occur at the master, with the updates distributed to the live slaves, whereas non-replicated operational data
can also be written on the slaves.
The only thing NSO does is to replicate the CDB data amongst the members in the high availability group.
It doesn't perform any of the otherwise high availability related tasks such as running election protocols in
order to elect a new master. This is the task of a High-Availability Framework (HAFW) which must be in
place. The HAFW must instruct NSO which nodes are up and down using methods from Ha class in the Java
library.
Alternatively, if we do not wish to run NSO with a full scale high availability framework, we can use the
NSO package in $NCS_DIR/examples.ncs/web-server-farm/ha/packages/manual-ha to manually control
a small high availability pair of two nodes and manually indicate which node is master and which is slave. If
the master dies, the operator will have to manually tell the slave, that it is now master.
Replication is supported in several different architectural setups. For example two-node active/standby
designs as well as multi-node clusters with runtime software upgrade.

High Availability: ncs.conf
<ha>
<ip>0.0.0.0</ip>
<port>4569</port>
<tick-timeout>PT20S</tick-timeout>
</ha>
 enabled: false by default

 ip: IP address to listen on if the node becomes master
 port: the TCP port on which the masters listens for incoming session from slaves
 tick-timeout: keepalive timer defaults to 20 seconds
 three lost keeepalives from slave indicate a dead slave to the master
 three lost keeepalives from master start a new master selection
NSO must be instructed through the ncs.conf configuration file that it should run in high availability mode.
The IP address and the port above indicates which IP and which port should be used for the communication
between the high availability nodes. The tick-timeout is a duration indicating how often each slave must send
a tick message to the master indicating liveness. If the master has not received a tick from a slave within 3
times the configured tick time, the slave is considered to be dead. Similarly, the master sends tick messages
to all the slaves. If a slave has not received any tick messages from the master within the 3 times the timeout,
the slave will consider the master dead and report accordingly.
High Availability Framework (HAFW) HAFW controls NSO
node state
 Default state: none (normal
nso1.beMaster
standalone operation) nso2.beSlave
HAFW
 HAFW can instruct NSO to become
master or slave
 Note! NSO does not come with an
automated implementation of HAFW Replicate CDB
NSO1 NSO2
Note! NSO installation contains an example for manual master/slave control:
examples.ncs/web-server-farm/ha/packages/manual-ha
A high availability node can be in one of three states: NONE, SLAVE or MASTER. Initially a node is in the
NONE state. This implies that the node will read its configuration from CDB, stored locally on file. Once the
high availability framework has decided whether the node should be a slave or a master the HAFW must
invoke either the methods Ha.beSlave(master) or Ha.beMaster().
When an NSO high availability node starts, it always starts up in mode NONE. This is consistent with how
NSO works without high availability enabled. At this point there are no other nodes connected. Each NSO
node reads its configuration data from the locally stored CDB and applications on or off the node may
connect to NSO and read the data they need.
At some point, the HAFW will command some nodes to become slave nodes of a named master node. When
this happens, each slave node tracks changes and (logically or physically) copies all the data from the master.
Previous data at the slave node is overwritten.
Note that the HAFW, by using NSO's start phases, can make sure that NSO does not start its northbound
interfaces (NETCONF, CLI, etc.) until the HAFW has decided what type of node it is. Furthermore, once a
node has been set to the SLAVE state, it is not possible to initiate new write transactions towards the node. It
is thus never possible for an agent to write directly into a slave node. Once a node is returned either to the
NONE state or to the MASTER state, write transactions can once again be initiated towards the node.

Clustering
In this topic you will learn about the clustering functionality available with Cisco NSO.
Clustering
 Clustering provides Cluster link
communication between
standalone NSO systems
NSO1 NSO2
 Remote devices can be
accessed through other NSO
systems
 Remote devices' configurations
are not stored locally
devices devices
The NSO Clustering feature essentially makes it possible for a Device Manager on one NSO to connect and
communicate with a Device Manager on another NSO. An NSO cluster consists of loosely coupled, yet
tightly integrated set of co-operating NSO nodes.
When cluster mode is enabled it is possible to add devices using /devices/device/remote-node (instead of
address/port). A device added in such a way does not store its configuration on that local NSO node, instead
that node will query the remote node whenever configuration data is read. In fact, all operations towards that
device (read/write of config/stats, as well as actions) are delegated to the remote NSO node in question.
Designing a cluster deployment requires planning. There can be many reasons to use clustering: scaling
(handling more devices than a single node can handle), partitioning considerations (for example delegating
Device Manager responsibility according to geographical or network topological considerations). Another
reason can be to spread out services (services can be made to run on different cluster nodes).
Clustering Use Case: Service/Device Partitioning
Service
Mgmt
 Top level NSO or NSOs are used for
service management
 Bottom level NSOs are used for device
management
Device Device Device

Mgmt Mgmt Mgmt
The figure illustrates the separation of NSO functionality into two levels in a cluster based on service and
device management:
 Top level NSO or NSOs are used for service management
 Bottom level NSOs are used for device management

Clustering Use Case: Geographic Redundancy
Global
 Each cluster node responsible for its

region
 Each cluster supports all required
services
Americas EMEA APAC
The figure illustrates a use case where the load is distributed among geographical regions. This minimizes
the performance impact on NSO by splitting the managed devices among the regional NSOs.
Clustering Use Case: Service Partitioning
Global
 Each cluster node responsible for

its set of services and devices
 Accommodates different
integration requirements and
administrative domains
Network Data Center Applications

Services Services Services
The next use case can also reduce the load on NSOs but using and additional layer of separation by making
different NSOs responsible for different sets of services. This may also be a requirement in case there are
separate administrative domains for different types of services.

Clustering with High Availability
Master Slave
 Each independent cluster node can

also be implemented for high
availability
 The two features are independent
 Masters should be responsible for
remote node communication
Master Slave Master Slave Master Slave
The figure illustrates a combination of high availability and scalability clustering where each cluster node is
implemented as a pair of high availability nodes (master and slave).
Clustering Implementation
Implementation steps: 1. Add remote node
1. Add remote nodes

2. Add remote devices Cluster link
NCS1 NCS2
Requirements:
2. Add remote devices
 Each node must have all the
NEDs of configured remote
nodes locally installed
devices devices
The figure illustrates the two steps needed to implement clustering:

 Configure remote cluster nodes in local NSO
 Add remote devices to local NSO
The prerequisite for the two steps is to ensure that the local NSO has all the required Network Element
Drivers (NEDs) for the added remote devices.

Cluster Configuration: Enable Northbound NETCONF
cisco@nso:~$ sudo vim /etc/ncs/ncs.conf

Edit ncs.conf
<netconf-north-bound>
<transport> Enable northbound

<ssh> NETCONF over SSH
<ip>0.0.0.0</ip> for NSO cluster
<port>2022</port> communication
</ssh>
</transport>
</netconf-north-bound>
cisco@nso:~$ ncs --reload Reload the modified

configuration
In order for NSO systems to be able to communicate you need to enable northbound NETCONF on port
2022.
Cluster Configuration: Add Remote Nodes
admin@nso(config)# cluster authgroup nso-global ?
default-map - Remote authentication parameters for users not in umap
umap - Map NCS users to remote authentication parameters Use in case the
admin@nso(config)# cluster authgroup nso-global default-map ? same credentials
remote-name - Specify node user name are valid across
remote-password - Specify the remote password the entire cluster
same-pass - Use the local NCS user name as the remote user name
same-user - Use the local NCS user name as the remote user name
admin@nso(config)# cluster authgroup nso-global default-map same-user same-pass
admin@nso(config)# cluster remote-node nso-am address 10.65.0.2 authgroup nso-global
admin@nso(config)# cluster remote-node nso-emea address 10.129.0.2 authgroup nso-global
admin@nso(config)# cluster remote-node nso-apac address 10.193.0.2 authgroup nso-global
Commit complete. Retrieve public SSH keys
admin@nso(config)# cluster remote-node nso-am ssh fetch-host-keys
admin@nso(config)# cluster remote-node nso-emea ssh fetch-host-keys from cluster neighbors
admin@nso(config)# cluster remote-node nso-apac ssh fetch-host-keys
Assuming we have the new NSO node, ncs-global, up and running we need to first add the three other nodes
to its configuration. The very first step is to set up authentication configuration. NSO uses NETCONF over
SSH to communicate to other nodes in the cluster, the simplest way to set up authentication is to have NSO
pass on the credentials one has logged in with on to the next NSO.

Cluster Configuration: Add Remote Devices
admin@nso(config)# devices device pe-am-1101 remote-node ncs-am
admin@nso(config)# devices device pe-am-1102 remote-node ncs-am Define all remote
admin@nso(config)# devices device pe-am-1201 remote-node ncs-am devices that are
...
required
admin@nso(config)# devices device pe-am-1201 remote-node ncs-emea
admin@nso(config)# devices device pe-am-1201 remote-node ncs-emea
...
admin@nso(config)# devices device pe-am-1201 remote-node ncs-apac

...
Commit complete.
Once the other nodes in the cluster have been created we can start adding remote devices connected to those
nodes.
Scalable System Management
In this topic you will learn how to use the NCT toolset to efficiently manage a larger NSO
install base.
Scalable System Management: NCT Toolset
 Large managed environments may make use

of a number of NSO system (standalone, a
single cluster or even a number of clusters)
 Cumbersome repetitive maintenance tasks NSO2
 NCS Toolset provided with NSO 4.1 to NSO7
simplify maintenance of multiple NSO
systems
NSO1 NSO4
NSO3 NSO8
NSO6 NSO5
NCT is a collection of tools that can be used to install and manage NCS nodes.

 Any NSO system can be used as NCT node
NSO2
SSH NSO7
NCT
NSO1 NSO4
NCT node used NSO3 NSO8

Managed NSO
to manage other
nodes
NSO nodes NSO5
NSO6
Each NCS node can be operated on independently but the main idea is that NCT can operate on a set of NSO
nodes. To operate on a set of NSO nodes a, so called, hostsfile is needed. A hostsfile consists of host entries
according to the following example.
Hostsfile defines rules for
accessing remote nodes
{"IP-address",[options]}
NSO2
NSO7
SSH
NCT
{"10.65.0.2",[{ssh_user,"admin"}, {ssh_pass,"admin"}]}. NSO1 NSO4

{"10.129.0.2",[{ssh_user,"admin"}]}.
{"10.193.0.2",[{ssh_user,"admin"}]}.
NSO3 NSO8
NCT option rules:
 Omit the starting "--" from NCT options
 Replace "-" with "_"
NSO5
 E.g. "--ssh-user" becomes "ssh_user" NSO6
A hostsfile is a plain text file that consists of host-entries, containing individual options for each entry. Each
entry - called a a Tuple, that begin with a ‘{’ bracket and ends with a ‘}.’ - consists of a Hostname/IP-
Address, enclosed in double quotes and a list of options, where the list begin with a ‘[’ bracket and ends with
a corresponding ‘]’ bracket.
Each option is represented as a tuple with the switch name and its value, and if it is an unary switch it is
represented as just the switch name. The ‘-’ in a switch corresponds to a ‘_’ in the hostsfile. For example, the
switch ‘--ssh-user’ correspond to ‘ssh_user’ in the hostsfile.

NCT: Hostsfile Options
 name
 Each NSO node can be given a name
 Names can be referenced to execute NCT action on nodes
{"10.65.0.2",[{name,"nso-am1"}]}.
{"10.65.64.2",[{name,"nso-am2"}]}. NSO2
{"10.129.0.2",[{name,"nso-emea1"}]}.
{"10.129.64.2",[{name,"nso-emea1"}]}. nso-am1
{"10.193.0.2",[{name,"nso-apac1"}]}. NSO7
{"10.193.0.2",[{name,"nso-apac2"}]}.
apac nso-am2
 groups
 Multiple nodes can be grouped NSO1 NSO4
 Used to execute NCT actions on multiple nodes nso-apac1 nso-apac2
{"10.65.0.2",[{groups,["am","svc"]}]}. NSO3
{"10.65.64.2",[{groups,["am","dev"]}]}. NSO8
{"10.129.0.2",[{groups,["emea","svc"]}]}. nso-apac3 nso-emea2
{"10.129.64.2",[{groups,["emea","dev"]}]}.
{"10.193.0.2",[{groups,["apac","svc"]}]}.
{"10.193.0.2",[{groups,["apac","dev"]}]}. NSO6 NSO5
nso-emea3
© 2016 Cisco and/or its affiliates. All rights reserved.
nso-emea1 emea Cisco Network Services Orchestrator 36
Each managed NSO node can be given a name (alias) that can then be used by NCT commands to reference
the NSO nodes by name. Often it can also be useful to be able to group a subset of the Hosts in the hostsfile
when you want to restrict or group an operation to only those Hosts. This can be done with the group
mechanism.
name
A name representation of the host. It is mandatory for the nct-move-device command. Example:
{"192.168.23.99",[{name, "paris"}, ... ]}.
{"192.168.23.98",[{name, "london"}, ... ]}.
Mandatory for nct-move-device.
groups
A list of groups the host belongs to. Example:
{"192.168.23.99",[{groups, ["groupA", "groupB"]}, ... ]}.
{"192.168.23.98",[{groups, ["groupB", "groupC"]}, ... ]}.
NCT: Hostsfile Options (Cont.)
 SSH Access:
 Options: ssh_user, ssh_pass, ssh_port
 Static SSH access parameters to log into remote NSO node shell
 NETCONF:
 Options: netconf_user, netconf_pass, netconf_port
 Static NETCONF access parameters to log into remote NSO CLI
 NSO System Directories:
 Options: install_dir, run_dir, config_dir, log_dir
 NSO system directories used on remote NSO node
 NSO Device Migration:
 Options: service_node, device_node
 Used to implement device migration between NSO nodes
The Hostsfile can contain any option available to the NCT tool. The options are typically in the form of --
option. Remember, each Hostsfile option omits the startin "--" and has the other ‘-’ characters in a switch
replaced by the ‘_’ character in the Hostsfile. For example, the switch ‘--ssh-user’ correspond to ‘ssh_user’ in
the hostsfile.
Common options for NCT tools
--concurrent BOOL
Each HOST will be operated upon concurrently. The default value is true. If set to false, each HOST will be
dealt with in sequence. Obviously, the default behavior often results in a faster total execution time.
However, when debugging a command it can be useful to only execute one HOST at a time.
--name NAME
Restrict the command to only operate on the given NAME.
--group GROUP[,GROUP]
Restrict the command to only operate on the given GROUP or groups.
--groupoper GROUPOPER
If several groups are specified with the --group switch. This switch defines if the union or intersection of
those groups should be used. Possible values are: "or" (default) or "and".
--help
Will print out a short help text and then terminate the command.
-h, --host HOST[,HOST]+
Define one HOST, or several comma separated HOST. The given hosts are the ones the command will
operate upon.
--hostsfile HOSTSFILE
The HOSTSFILE containing the HOST entries. By setting the environment variable ‘NCT_HOSTSFILE’ to
HOSTSFILE this switch can be omitted.

--progress BOOL
If BOOL is true, then some progress indication will be displayed. The default is false.
--ssh-pass SSHPASS
The SSH password to be used.
--ssh-port SSHPORT
The SSH Port number to be used (default: 22).
--ssh-timeout SSHTIMEOUT
The SSH timeout is specified in milliseconds. Depending on the type of operation. This timeout may have to
be increased.
--ssh-user SSHUSER
The SSH user to be used.
--timeout TIMEOUT
A general timeout which may expire if the ongoing operations takes a too long time to finish. In this case it
may be good to increase this value.
-v, --verbose VERBOSE
To increase the output two werbose levels exist. Level 2 will output as much information as possible. Level 1
will output a little less information. This is mostly useful debugging a command.
Examples of options in Hostsfile
ssh_user (--ssh-user)
SSH User for the host. Example:
{"192.168.23.99",[{ssh_user, "admin"}, ... ]}.
{"192.168.23.98",[{ssh_user, "oper"}, ... ]}.
ssh_pass (--ssh-pass)
SSH Password for the host. Example:
{"192.168.23.99",[{ssh_pass, "secret"}, ... ]}.
{"192.168.23.98",[{ssh_pass, "secret"}, ... ]}.
ssh_port (--ssh-port)
SSH PORT for the host. Example:
{"192.168.23.99",[{ssh_port, 22}, ... ]}.
{"192.168.23.98",[{ssh_port, 24}, ... ]}.
netconf_user (--netconf-user)
NETCONF User for the host. Example:
{"192.168.23.99",[{netconf_user, "admin"}, ... ]}.
{"192.168.23.98",[{netconf_user, "oper"}, ... ]}.
netconf_pass (--netconf-pass)
NETCONF Password for the host. Example:
{"192.168.23.99",[{netconf_pass, "secret"}, ... ]}.
{"192.168.23.98",[{netconf_pass, "secret"}, ... ]}.
netconf_port (--netconf-port)
NETCONF PORT for the host. Example:
{"192.168.23.99",[{netconf_port, 2022}, ... ]}.
{"192.168.23.98",[{netconf_port, 2024}, ... ]}.
install_dir (--install-dir)
This is the directory where static files, primarily the code and libraries for the NCS daemon, are installed.
The actual directory used for a given invocation of the installation script is InstallDir/ncs-VSN, allowing for
coexistence of multiple installed versions.
The currently active version is identified by a symbolic link InstallDir/current pointing to one of the ncs-
VSN directories. If the install_dir option is omitted, /opt/ncs will be used. Example:
{"192.168.23.99",[{install_dir, "/opt/ncs"}, ...]}.
config_dir (--config-dir)
This directory is used for config files, e.g. ncs.conf. If the config_dir option is omitted, /etc/ncs will be used.
Example:
{"192.168.23.99",[{config_dir, "/etc/ncs"}, ...]}.
run_dir (--run-dir)
This directory is used for run-time state files, such as the CDB data base and currently used packages. If the
run_dir option is omitted, /var/opt/ncs will be used. Example:
{"192.168.23.99",[{run_dir, "/var/opt/ncs"}, ...]}.
service_node (--service-node)
The name of the node serving as a service node to the host. Must correspond with the name option of the
service node. It is mandatory for the nct-move-device command. Example:
{"192.168.23.99",[{name, "paris"}, ... ]}.
{"192.168.23.11",[{service_node, "paris"}, ... ]}.
device_nodes (--device-node)
A list of names of the nodes serving as a device nodes to the host. Must correspond with the name option of
the device node. It is mandatory for the nct-move-device command. Example:
{"192.168.23.99",[{device_nodes, ["parisd1", "parisd2"]}, ... ]}.
{"192.168.23.11",[{name, "parisd1"}, ... ]}.
{"192.168.23.12",[{name, "parisd2"}, ... ]}.
Refer to the NSO manual pages for a complete list of the supported NCT Hostsfile options.

NCT Toolset
cisco@nso:~$ nct
Usage: nct <command>  Use nct tool
COMMANDS
backup Invoke the nct-backup script
check Invoke the nct-check script  Supply desired command
cli-cmd Invoke the nct-cli-cmd script
copy Invoke the nct-copy script  Supply the necessary
ha Invoke the nct-ha script
install
load-config
Invoke the nct-install script
Invoke the nct-load-config script
parameters
move-device Invoke the nct-move-device script
packages Invoke the nct-packages script  use nct --help <command>
patch Invoke the nct-patch script
ssh-cmd Invoke the nct-ssh-cmd script to get the details for
start Invoke the nct-start script
stop Invoke the nct-stop script individual commands
upgrade Invoke the nct-upgrade script
get-logs Invoke the nct-get-logs script
help Display the man page for <command>
OPTIONS
-h, --help Show this help text.
cisco@nso:~$
Issue the ncs command to display all options available:

 backup: Invoke the nct-backup script to perform the ncs-backup operation on the selected NSO nodes.
 check: Invoke the nct-check script to perform a basic check of the NCT functionality.
 cli-cmd: Invoke the nct-cli-cmd script to execute the selected NSO CLI commands on the selected NSO
nodes.
 copy: Invoke the nct-copy script to copy the selected files to the selected NSO nodes.
 ha: Invoke the nct-ha script to manage the tailf-hcc package on the selected NSO nodes.
 install: Invoke the nct-install script to install NSO on the selected Linux systems.
 load-config: Invoke the nct-load-config script to upload XML configurations to the selected NSO
nodes.
 move-device: Invoke the nct-move-device script to migrate managed devices from one NSO node to
another.
 packages: Invoke the nct-packages script to manage packages on the selected NSO nodes.
 patch: Invoke the nct-patch script to install NSO beam patches on the selected NSO nodes.
 ssh-cmd: Invoke the nct-ssh-cmd script to execute arbitrary shell commands on the selected NSO nodes.
 start: Invoke the nct-start script to start the NSO system on the selected NSO nodes.
 stop: Invoke the nct-stop script to stop the NSO system on the selected NSO nodes.
 upgrade: Invoke the nct-upgrade script to upgrade the selected NSO nodes.
 get-logs: Invoke the nct-get-logs script to tar the logs and retrieve them from the selected NSO nodes.
 help: Display the man page for <command>
NCT Toolset: Load Configuration
 Load startup configuration file ncs.conf (requires NSO config reload):

cisco@nso:~$ nct load-config --file ncs.conf --type ncs-conf
 Load configuration using init XML file (requires NSO restart):

cisco@nso:~$ nct load-config --file config.xml --type cdb-init
 Load configuration using XML file and ncs_load command on NSO

nodes:
cisco@nso:~$ nct load-config --file config.xml --type cdb
With the nct-load-config command it is possible to load XML configuration files to NCS hosts, either
running NSO instances or as initial configuration.
NCT Load Configuration Options
--file FILE
The configuration xml file containing CDB configuration, or an ncs.conf file.
Example: `config.xml | ncs.conf'
--type TYPE
The type of configuration file. See the TYPE section. Valid types are: cdb, cdb-init or ncs-conf.
--install-dir InstallDir
This is the directory where static files, primarily the code and libraries for the NCS daemon, are installed.
The actual directory used for a given invocation of the installation script is InstallDir/ncs-VSN, allowing for
coexistence of multiple installed versions. The currently active version is identified by a symbolic link
InstallDir/current pointing to one of the ncs-VSN directories. If the --install-dir option is omitted, /opt/ncs
will be used for InstallDir.
--config-dir ConfigDir
This directory is used for config files, e.g. ncs.conf. If the --config-dir option is omitted, /etc/ncs will be used
for ConfigDir.
--run-dir RunDir
This directory is used for run-time state files, such as the CDB data base and currently used packages. If the -
-run-dir option is omitted, /var/opt/ncs will be used for RunDir.

NCT Toolset: Create Backup
 Use nct backup tool to back up NSO nodes Service Node
 Back up all nodes:

cisco@nso:~$ nct backup --hostsfile hostsfile
... Device Nodes
NSO2
 Back up a group of nodes: NSO1 NSO2
cisco@nso:~$ nct backup --hostsfile hostsfile --group device_nodes
...
 Back up a single node:

cisco@nso:~$ nct backup --hostsfile hostsfile --name nso-am1
SSH Check to 10.65.0.2:22 [nso-am1]
SSH OK : 'ssh sudo /opt/ncs/current/bin/ncs-backup --non-interactive' returned: INFO
Backup /var/opt/ncs/backups/ncs-4.1.1@2016-03-05T01:07:47.backup created successfully
cisco@nso:~$
Suggestion: add path to hostsfile into NCT_HOSTSFILE environment variable

The nct-backup will perform an NCS backup on the specified Host(s) using the built in NSO functionality.
At success, the name of the created backup file will be returned.
This command has no specific options, only the options common to all NCT commands.
NCT Toolset: Move Device
 Use nct move-device tool to move Service Node
a device from one NSO to another NSO2
 Prerequisites:
Device Nodes
 Hostsfile: name, device_node,
NSO1 NSO2
service_node, REST options
 Nodes have REST enabled
 SSL enabled (or disable SSL for
Migrate device from
REST in Hostsfile) one device NSO
devices node to another devices
cisco@nso:~$ nct move --device pe-1201-01 --from nso-am1 --to nso-am2

...
cisco@nso:~$
The nct-move-device is a command can be used for moving a managed device from one NSO node to
another using the REST API of NSO. Note that this command requires the cluster topology to be described in
the
Hostsfile.
NCT Move Device Options
--device DEVICE
The name of the device to move.
--from FROM
The NCS device node name, as specified in the hostsfile.
--to TO
The NCS device node name, as specified in the hostsfile.
--rest-pass RESTPASS
The REST password to be used (default: admin).
--rest-port RESTPORT
The REST Port number to be used (default: 8080).
--rest-user RESTUSER
The REST user to be used (default: admin).
--rest-SSL BOOLEAN
REST via SSL true/false (default: true).

NCT Toolset: Execute NSO CLI Commands
nct
 Use nct cli-cmd tool execute arbitrary NSO
CLI commands on selected NSO nodes
cisco@nso:~$ nct cli-cmd -c "show device list"
Cli command to 10.65.0.2 [nso-am1]

NAME ADDRESS DESCRIPTION NED ID ADMIN
STATE
------------------------------------------------------ nso-am1 nso-emea1 nso-apac1
--
CE11 127.0.0.1 - cisco-ios unlocked
...
Cli command to 10.129.0.2 [nso-emea1]

NAME ADDRESS DESCRIPTION NED ID ADMIN
STATE
------------------------------------------------------
--
...
The nct-cli-cmd is a command to execute NSO CLI commands on one or several NSO systems.
-c CMD or --cmd CMD
The CMD argument is a string that can contain any valid CLI command that you want to execute on the
host(s). Note that the command(s) are piped to the ncs_cli executable.
NCT Toolset: Package Management
Options:
 Default action is to list packages: -c <command>
cisco@nso:~$ nct packages install
Package Info at 10.65.0.2:8080
ncs-4.1.1-cisco-ios-4.0.4 (loaded) Statuses: deinstall
ncs-4.1.1-cisco-iosxr-4.1 (loaded) installable fetch
ncs-4.1.1-juniper-junos-3.0.21 (loaded)
l2vpn-1.0 (loaded) installed --file <package file>
l3mplsvpn-1.0 (loaded) loaded --package <package name>
...
 Upload a new package file (i.e. make it "installable"):

cisco@nso:~$ nct packages --file ncs-3.3-tailf-hcc-3.0.8.tar.gz --fetch
 Install a package (i.e. make it "installed"):

cisco@nso:~$ nct packages --package ncs-3.3-tailf-hcc-3.0.8 -c install
Use the nct-packages command to install, uninstall, load NSO packages and retrieve related package status
information, such as if the package is installed, loaded or just installable.
NCT Packages Options
-c, --cmd CMD
The default CMD is ‘list’ which will list all the packages in host(s) and their status. The status can be any of
‘installable’, ‘installed’ or ‘loaded’. These values can also be used as a CMD and will then only show those
packages with this status. To get the NCS package moved to host(s), i.e to make it ‘installable’, use ‘fetch’ as
the CMD. To install or deinstall use the ‘install’ or ‘deinstall’ value as the CMD. To load or unload a
package into a running NCS use the ‘reload’ CMD. The ‘fetch’ command require the ‘--file’ switch to be
used. The ‘install’ and ‘deinstall’ require the ‘--package’ switch.
--file FILE
The package file name. Example: ‘ncs-3.3-tailf-hcc-3.0.8.tar.gz’. This switch is used in combination with the
‘-c fetch’ switch.
--package PACKAGE
The package name. Example: ‘ncs-3.3-tailf-hcc-3.0.8’. This switch is used in combination with either ‘-c
install’ or ‘-c deinstall’ switches.

1. Determine if given NSO version is
NCT Toolset: Upgrade NSO installed on the host
 Upgrade NSO: 2. Determine if given NSO version isn’t
already running
cisco@nso:~$ nct upgrade --ncs-vsn 4.1.1
3. Ensures that ‘installable’ packages exist
 The -c available option can be that corresponds to the (old) already
used to only verify the installed packages
availability of upgrade version 4. Backup NSO (default action, but
 Backup action can be disabled optional)
using the --backup false option 5. Uninstall old packages
 Reloading can be disabled 6. Install new packages
using the --reload-packages 7. Stop NSO
false option 8. Rearrange the symbolic links under
InstallDir
9. Start NSO (default is to also reload all
packages, but optional)
The nct-upgrade command will upgrade an NSO release on the specified host(s) using the ‘--cmd’ and ‘--
ncs-vsn’ switches. The default is to first do an NCS backup and to reload any packages. This behavior can be
changed with the ‘--backup’ and ‘--reload_packages’ switches.
When doing an upgrade, this command will do the following:
1. Assert the given NCS version really is installed on the Host.
2. Assert that given NCS version isn’t already running.
3. Make sure that there exist ‘installable’ packages that corresponds to the (old) already installed packages.
4. Backup NCS (default action, but optional)
5. Uninstall the old packages, then install the new packages.
6. Stop NCS
7. Rearrange the symlinks under InstallDir
8. Start NCS (default is to also reload all packages, but optional)
NCT Upgrade Options
--backup BOOL
If ‘true’ (default), an NCS backup will be performed before the NCS upgrade takes place. This can be turned
off by specifying ‘false’ as the BOOL value.
-c, --cmd CMD
The CMD can be either upgrade (default) or available. The former will perform an NCS upgrade and the
latter will show all installed releases on host(s).
--ncs-vsn NCSVSN
The NSCVSN is a string containing the NCS version number. Example: ‘3.2.1’
--reload-packages BOOL
If ‘true’ (default), any packages will be reloaded when the new (upgraded) NCS is started. This can be turned
off by setting the BOOL value to ‘false’.
Other NCT Tools
 Copy files to NSO nodes (/tmp is default destination):
cisco@nso:~$ nct copy --file neds.tar.gz --to-dir /opt/resources
 Retrieve tared logs:

cisco@nso:~$ nct get-logs
 Install NSO:
cisco@nso:~$ nct install nso-4.1.1.linux.x86_64.installer.bin
Install NCS to 10.65.0.2:22
Installation started, see : /tmp/nso-4.1.1.linux.x86_64.installer.bin.log
Install NCS to 10.129.0.2:22

Installation started, see : /tmp/nso-4.1.1.linux.x86_64.installer.bin.log
...
 Start NSO:  Stop NSO:

cisco@nso:~$ nct start cisco@nso:~$ nct stop
Refer to the manual pages for a complete list and description of all NCT commands. the figure illustrates
how to install, start or stop the NSO system and how to copy file to an NSO system or retrieve logs from a
NSO system.

System Troubleshooting
In this topic you will learn about the common troubleshooting strategies for the Cisco NSO
system and services.
System Troubleshooting
 Installation problems
 Startup issues
 Service design challenges
 Service instance deployment problems
A number of issues may arise in a large and complex environment.
Some challenges may occur during system setup stage:

 System installation
 Service design
Some challenges may occur during normal system operation:

 Startup issues
 Service instance deployment problems
System Troubleshooting Strategies
 Run NSO in verbose mode and in foreground
 Tail relevant log files:
 System install: /var/logs/ncs/ cisco@nso:~$ ncs --verbose --foreground
...
 Local install: in logs subdirectory
of the running directory
cisco@nso:~$ tail –f /var/log/ncs/ncs.log
...
Relevant log files:
 ncs.log: system event logs
 audit.log: system access logs
 devel.log: detailed debugging log useful for development
 xpath.trace: detailed XPath parsing log useful for development
When NSO is started, give the --verbose (abbreviated -v) and --foreground flags. This will prevent NSO
from starting as a daemon and cause some messages to be printed on the stdout.
 $ ncs --verbose --foreground ...
To find out what NSO is/was doing, browsing NSO's log files is often helpful. In the examples, they are
called 'devel.log', 'ncs.log', 'audit.log'. If you are working with your own system, make sure the log files are
enabled in ncs.conf. They are already enabled in all the examples.

System Status
cisco@nso:~$ ncs --status admin@nso# show ncs-state
vsn: 4.1.1 ncs-state db-mode running
SMP support: no ncs-state version 4.1.1
Using epoll: yes ncs-state epoll true
available modules: ncs-state daemon-status started
backplane,netconf,cdb,cli, ncs-state loaded-data-models data-model
running modules: IANA-IT
backplane,netconf,cdb,cli,sn …
status: started
namespaces: http://tail-
f.com/ns/aaa/1.1 pref
…
 Shell command ncs --status or CLI command show ncs-state provide

a comprehensive status report on the NSO system
NSO will give you a comprehensive status report if you call ncs –status. NSO status information is also
available as operational data under /ncs-state (e.g. by using the show ncs-state CLI command).
Restarting NSO
 After changing the configuration (ncs.conf) it is enough to reload the
configuration:
cisco@nso:~$ sudo ncs --reload cisco@nso:~$ ncs --reload
 Restarting NSO:
cisco@nso:~$ sudo /etc/init.d/ncs cisco@nso:~$ ncs --stop
restart cisco@nso:~$ ncs
 Restarting NSO and reloading packages: Local installation

cisco@nso:~$ ncs --stop
cisco@nso:~$ ncs --with-package-reload
The figure illustrates the various options available to re-initialize the NSO system:
 After changing the ncs.conf file it is enough to trigger a reload using the ncs --reload command.
 When a complete restart is required you should use the /etc/init.d/ncs restart command if you are using
the system installation or use the ncs --stop command to stop the server and ncs to start the server. Note
that a server restart does not initiate a package reload action. You should use the packages reload CLI
command or use the --with-packkage-reload flag when starting a locally-installed NSO.

Tracing Southbound NETCONF
 Provides NETCONF/NED traffic tracing towards devices
 A good troubleshooting approach Re-connect or sync required
to enable trace log
Global settings:
admin@nso(config)# devices global-settings trace pretty
admin@nso(config)# devices global-settings trace-dir logs
admin@nso# devices disconnect
admin@nso# devices connect
Per-device settings:
admin@nso(config)# devices device rtr-sf-pe122 trace pretty
admin@nso# devices device rtr-sf-pe122 disconnect
admin@nso# devices device rtr-sf-pe122 connect
admin@nso# file show <path>/ned-cisco-ios-rtr-sf-pe122.trace
Log file name is constructed from the NED ID and the hostname
Service model or NED development may require additional troubleshooting information that can be
generated by enabling NETCONF trace logs. The figure illustrates how to enable logs globally or on per-
device basis.
It is possible to turn on and off NETCONF/NED traffic tracing. This is often a good way to troubleshoot
problems. In order to understand the trace output, a basic prerequisite is a good understanding of the
NETCONF RFC. Similarly for CLI NEDs, a good understanding of the CLI capabilities of the managed
devices is required. To turn on southbound traffic tracing, we need to enable the feature and we must also
configure a directory where we want the trace output to be written. It is possible to have the trace output in
two different formats, pretty and raw. The pretty mode indents all the XML data for enhanced readability and
the raw mode does not. Sometimes when the XML is broken, raw mode is required.
Gathering Support Information
 When opening a support request it is important to gather the required
information:
 Transcript and the configuration needed to reproduce an issue
 Log files: make sure you enable the error logs when reproducing the issue
 Use ncs –status to collect system information
 Use the ncs --debug-dump <dump-file> options to create a dump file
When reporting an issue to the NSO support team it is recommended to collect as much valuable data which
can help resolve the issue in a timely manner. In addition to the previously mentioned troubleshooting
options you should also provide a dump file and error logs when having problems with the NSO system.
Make sure you enable logging before reproducing an issue to prepare the support information.
The following sections provide some additional information regarding the available troubleshooting
mechanisms.
Transcript
When contacting support, it often helps the support engineer to understand what you are trying to achieve if
you copy-paste the commands, responses and shell scripts that you used to trigger the problem.
Check data provider

If you are implementing a data provider (for operational or configuration data), you can verify that it works
for all possible data items using ncs --check-callbacks.
Debug dump
If you suspect you have experienced a bug in NSO, or NSO told you so, you can give Support a debug dump
to help us diagnose the problem. It contains a lot of status information (including a full ncs --status report)
and some internal state information. This information is only readable and comprehensible to the NSO
development team, so send the dump to your support contact. A debug dump is created using ncs --debug-
dump mydump1. Many interesting traces will wash away with time, or stay undetected if there are lots of
irrelevant facts in the dump.
Debug error log

Another thing you can do if you suspect you have experienced a bug in NSO, is to enable the error log. The
logged information is only readable and comprehensible to the NSO development team, so send the log to
your support contact. By default, the error log is disabled. To enable it, add this chunk of XML between
<logs> and </logs> in your ncs.conf file:
<errorLog>
<filename>./error.log</filename>
</errorLog>
This will actually create a number of files called ./error.log*.
System dump
If NSO aborts due to failure to allocate memory (see Section 31.8, “Disaster management”), and you believe
that this is due to a memory leak in NSO, creating one or more debug dumps as described above (before
NSO aborts) will produce the most useful information for Support. If this is not possible, you can make NSO
produce a system dump just before aborting. To do this, set the environment variable $NCS_DUMP to a file
name for the dump before starting NSO. The dumped information is only comprehensible to the NSO
development team, so send the dump to your support contact.
System call trace

To catch certain types of problems, especially relating to system start and configuration, the operating
system's system call trace can be invaluable. This tool is called strace/ktrace/truss. Please send the result to
your support contact for a diagnosis. Running instructions below.
 Linux:
strace -f -o mylog1.strace -s 1024 ncs ...
 BSD:
ktrace -ad -f mylog1.ktrace ncs ...
kdump -f mylog1.ktrace > mylog1.kdump
 Solaris:
truss -f -o mylog1.truss ncs ...
Summary
 Reliability: backup, master/slave setup
 Performance: clustering
 Security: AAA setup
 Scalability: use NCT
 New features: upgrade to latest version
References

Lesson 4-3
Alarm Management and

Reporting
Overview
This lesson describes the capabilities of Cisco Network Services Orchestrator to provide
valuable information to operators such as alarms that indicate and incident and require
immediate operator action, or an on-demand report summarizing the health of the environment.
Objectives
 Understand and manage alarms in Cisco NSO
 Manage alarms thorough the Alarm Center or CLI
 Configure alarm management characteristics
 Create Cisco NSO system status report
Alarms Overview
This topic describes the Cisco NSO alarming capabilities.
Alarm Management
" An alarm denotes an undesirable state in a
resource for which an operator action is required"
 Alarms are enabled by

default
Retrieve alarms
 Alarm Center in Web UI View alarms
(SNMP, syslog)
provides an overview of (CLI or Web UI)
active alarms Cisco NSO
 Alarms can also be

accessed via the CLI
Monitoring System
Cisco NSO embeds a generic alarm manager. It is used for managing NSO native alarms and can easily be
extended with application specific alarms. Alarm sources can be notifications from devices, undesired states
on services detected or anything provided via the Java application programming interface (API).
NSO generates alarms for serious problems that must be remedied. Alarms are available over all northbound
interfaces and they exist at the path /alarms. NSO alarms are managed as any other alarms by the general
NSO Alarm Manager.
The NSO alarm manager also presents a northbound Simple Network Management Protocol (SNMP) view,
alarms can be retrieved as an alarm table, and alarm state changes are reported as SNMP Notifications.
Note Not every alarm has a service impact. Some alarms are considered minor, some of them may also
originate from the NSO itself and have nothing to do with the state of the service or the network.
Alarm Manager Alarm
SNMP Alarm
Handling
Managers
Clients
Alarm sources: Auto- generated Dedicated SNMP
northbound alarm MIB
 NSO states generate alarms interface
 Device events can generate alarms
 Any other source can be designed to Alarm Manager:
generate alarms  Alarm Model
 Alarm List
Alarm consumers:  Operator Actions
Alarms in CDB
 NSO CLI or WebUI
 SNMP agent Dedicated alarm API
 Custom software Custom application

SNMP Trap Receiver
…
First of all it is important to clearly define what an alarm means. “An alarm denotes an undesirable state in a
resource for which an operator action is required.” An alarms doesn’t necessarily mean that there is a service
outage or degradation. Typically there are alarms tiers that will denote the severity of the situation. Alarms
are often confused with general logging and event mechanisms, thereby overflooding the operator with
alarms. In NSO, the alarm manager shows undesired resource states that an operator should investigate. NSO
contains other mechanisms for logging in general. Therefore, NSO does not naively populate the alarm list
with traps received in the SNMP notification receiver.
Before looking into how NSO handles alarms it is important to define the fundamental concepts. We make a
clear distinction between alarms and events in general. Alarms should be taken seriously and be investigated.
Alarms have states, they go active with a specific severity, they change severity and they are cleared by the
resource. The same alarm may become active again. A common mistake is to confuse the operator view with
the resource view. The model described so far is the resource view. The resource itself may consider the
alarm cleared. The alarm manager does not automatically delete cleared alarms. An alarm that has existed in
the network may still need investigation. There are dedicated actions an operator can use to manage the
alarm list, for example delete alarms based on criteria’s such as cleared and date. These actions can be
performed over all north-bound interfaces.
Rather than viewing alarms as a list of alarm notifications NSO defines alarms as states on objects. The NSO
alarm list uses four keys for alarms: the alarming object within a device and the alarm type and an optional
specific problem. Alarm types are normally unique identifiers for a specific alarm state and are defined
statically. An alarm type corresponds to the well-known X.733 alarm standard tuple event type, and probable
cause. Specific problem is an optional key that is string based and can further redefine an alarm type at run-
time. This is needed for alarms that are not known before a system is deployed. Imagine a system with
general digital inputs. A MIB might specify traps called input-high, input-low. When defining the SNMP
notification reception, an integrator might define an alarm type called "External-Alarm". Input-high might
imply a major alarm and input-low might imply clear. At installation some detectors report "fire-alarm" and
some "door-open" alarms. This is configured at the device and sent as free text in the SNMP var-binds. This
is then managed by using the specific problem field of the NSO alarm manager to separate this different
alarm types.
The Alarm Manager has three main components:

 Alarm List: A list of alarms in NSO. Each list entry represents an alarm state for a specific device,
object within the device and an alarm type.
 Alarm Model: For each alarm type, you can configure the mapping to for example X.733 alarm standard
parameters that are sent as notifications northbound.
 Operator Actions: Actions to set operator states on alarms such as acknowledgement, and also actions to
administratively manage the alarm list such as deleting alarms.
The alarm manager is accessible over all northbound interfaces. A read-only view including an SNMP alarm
table and alarm notifications is available in an SNMP Alarm MIB. This MIB is suitable for integration to
SNMP based alarm systems.
In order to populate the alarm list there is a dedicated Java API. This API lets a developer add alarms, change
states on alarms etc. A common usage pattern is to use the SNMP notification receiver to map a subset of the
device traps into alarms.
Alarm Handling
 Alarms do not automatically go away

 Alarms always require operator
intervention:
 Critical: Immediate intervention
 Major: Intervention as soon as possible
How serious is
 Minor: Relay to admins/developers
it? What do I
 Warning: investigate during maintenance need to do?
 Notification: No immediate action required
 Operators always need to clear alarms
manually!
Alarms can have any of the following severity levels:

 Critical: Should be corrected immediately. Notify staff who can fix the problem. An example would be
L3 VPN service is down.
 Major: Should be corrected as soon as possible. Usually indicates failure in a secondary system such as
a backup service.
 Minor: Non-urgent failures that should be relayed to developers or admins, such as NSO internal errors.
 Warning: Non-urgent failures that should be investigated during the next maintenance window.
Example would be a revision error indicating that the device arrived with a newer known module
version. Upgrade the device Network Element Driver (NED) during the next maintenance window.
 Notification: Unusual events but not an error. No immediate action required.

Operator Actions
 The Alarm YANG model defines 5 alarm handling states:
 None: The operator has not intervened yet
 Ack: The operator acknowledged the alarm
 Investigation: The alarm is under investigation
 Observation: The alarm is under observation
 Closed: The alarm has been handled
Investigation Observation
None
Ack Closed
The alarm YANG model defines 5 alarm handling states:

 None: The operator has not intervened yet.
 Ack: The operator acknowledged the alarm. Basically, the alarm was seen by the operator and is
waiting further handling.
 Investigation: The alarm is under investigation by the operator or other staff.
 Observation: The alarm is under observation. This usually happens after the cause for the alarm has
been found and removed but needs further monitoring to confirm the root cause is truly gone.
 Closed: The alarm has been handled.
Alarm Management
This topic describes the alarm management interface in Cisco NSO using the WebUI or the
CLI.
Alarm Management
 Locally on NSO via CLI or WebUI

 Poll via SNMP or any other northbound API
 Forward alarms as SNMP traps
Alarm handling can be integrated with existing internal procedure used to handle incidents. NSO offers the
following alarm access capabilities:
 Locally on NSO via CLI or WebUI
 Poll via SNMP or any other northbound API
 Forward alarms as SNMP traps

Alarms via CLI
admin@ncs# show alarms

alarms summary indeterminates 0 Alarm summary information
alarms summary criticals 6 (show alarms summary)
alarms summary majors 6
alarms summary minors 0
alarms summary warnings 0
alarms alarm-list number-of-alarms 23
alarms alarm-list last-changed 2014-11-11T15:28:30.937263+00:00
alarms alarm-list alarm CE12 connection-failure /devices/device[name='CE12'] ""
is-cleared true
last-status-change 2014-08-20T06:48:18.776207+00:00
last-perceived-severity major Alarms
last-alarm-text "Connection to CE12 timed out"
status-change 2014-08-14T10:33:15.83104+00:00
(show alarms alarm- list)
received-time 2014-08-14T10:33:15.83104+00:00
perceived-severity major
alarm-text "Failed to authenticate towards device CE12: Unknown SSH host key"
...
The show alarms command will list the summary statistics for alarms and then the entire list of alarms with
their details (equivalent to what was shown in the WebUI on the previous page).
By selecting an individual alarm you will see the details such as all state changes, and all operation actions.
Each alarm entry shows the last status change for the alarm and also a child list with all status changes sorted
in chronological order.
 is-cleared: Was the last state change = clear?
 last-status-change: Time stamp for last status change
 last-perceived-severity: Last severity (not equal to clear)
 last-alarm-text: The last alarm text (not equal to clear)
 status-change:
— event-time: The time reported by the device
— received-time: The time that the state change was received by NSO
— perceived-severity
— alarm-text
Alarm type descriptions
 alarm-type: Base identity for alarm types. A unique identification of the fault, not including the
managed object. Alarm types are used to identify if alarms indicate the same problem or not, for lookup
into external alarm documentation, etc. Different managed object types and instances can share alarm
types. If the same managed object reports the same alarm type, it is to be considered to be the same
alarm. The alarm type is a simplification of the different X.733 and 3GPP alarm IRP alarm correlation
mechanisms and it allows for hierarchical extensions. A 'specific-problem' can be used in addition to the
alarm type in order to have different alarm types based on information not known at design-time, such
as values in textual SNMP Notification varbinds.
 ncs-dev-manager-alarm: Base type for all alarms related to the device manager. This is never reported,
sub-identities for the specific device alarms are used in the alarms.
 ned-live-tree-connection-failure: Failed to connect for one of the optional live tree NEDs.
 dev-manager-internal-error: An internal error in NSO device manager.
 final-commit-error: A managed device validated a configuration change, but failed to commit. When
this happens, NSO and the device are out of sync. Reconcile by comparing and sync-from or sync-to.
 commit-through-queue-blocked: A commit was queued behind a queue item waiting to be able to
connect to one of its devices. This is potentially dangerous since one unreachable device can potentially
fill up the commit queue indefinitely.
 revision-error: A managed device arrived with a known module, but too new revision. Upgrade the
Device NED using the new YANG revision in order to use the new features in the device.
 missing-transaction-id: A device announced in its Network Configuration Protocol (NETCONF) hello
message that it supports the transaction-id as defined in http://tail-f.com/yang/netconf-monitoring.
However when NSO tries to read the transaction-id no data is returned. This usually a case of
misconfigured NACM rules on the managed device. The NSO check-sync feature will not work.
 configuration-error: A device was badly configured in a manner making it unusable.
 commit-through-queue-failed: A queued commit failed. The device is now out of sync.
 connection-failure: NSO failed to connect to a managed-device. Verify address, port authentication,
check that the device is up and running.
 out-of-sync: A managed device is out of sync with NO. Reconcile by comparing sync-from or sync-to.
 ncs-snmp-notification-receiver-alarm: The snmp-notification-receiver could not setup its configuration,
either at startup or when reconfigured. Snmp notifications will now be missed. Check the error-message
and change the configuration.
 receiver-configuration-error: An SNMP Notification Receiver configuration error prevented it from
starting.
 ncs-package-alarm: Base type for all alarms related to packages. This is never reported, sub-identities
for the specific package alarms are used in the alarms.
 package-load-failure: NSO failed load a package. Check the package for the reason.
 package-operation-failure: A package has some problem with its operation. Check the package for the
reason.
 ncs-service-manager-alarm: Base type for all alarms related to the service manager. This is never
reported, sub-identities for the specific service alarms are used in the alarms.

Inspecting Alarms (Cont.)
admin@ncs(config)# show alarms alarm-list alarm PE* | select last-perceived-severity | select is-cleared | select status-change | tab
LAST
IS PERCEIVED PERCEIVED
DEVICE TYPE CLEARED SEVERITY EVENT TIME SEVERITY ALARM TEXT
-----------------------------------------------------------------------------------------------------------------------------------------------------------
PE11 connection-failure false major 2015-06-17T13:49:45 cleared Connected as admin
2015-06-21T06:55:18 major Failed to connect to device PE11: connection refused: Connection refused
2015-06-21T08:11:06 cleared Connected as admin
2015-06-26T10:23:06 major Failed to connect to device PE11: connection refused: ned_connect_cli read timeout
Alarm is still 2015-06-29T06:38:09 cleared Connected as admin
active. 2015-06-29T06:39:19 cleared Connected as admin
PE12 connection-failure true major 2015-06-17T06:44:43 cleared Connected as admin
...
The figure illustrates a list of alarms on PE devices. You can see that one of them is still active (not cleared).
Such alarms require immediate action. They will prevent any changes from being pushed down to this device
until the incident is resolved.
Operator Actions None
Acknowledged
 The alarm manager also defines Alarm
operator actions for handling alarms. Observation
States
 Use NSO or an existing monitoring Investigation
system to handle alarms. Closed
admin@ncs# alarms alarm-list alarm PE11 connection-failure /devices/device[name='PE11'] ""

handle-alarm state investigation
Set alarm state.
admin@ncs# show alarms alarm-list alarm PE11 alarm-handling
SPECIFIC
DEVICE TYPE MANAGED OBJECT PROBLEM TIME
STATE USER DESCRIPTION
-------------------------------------------------------------------------------------------
----------------------------------------------
PE11 connection-failure /devices/device[name='PE11'] 2015-07-
30T06:30:12.384945+00:00 investigation admin -
Operator actions can set operator states on alarms (for example, acknowledged, observed, and so on), and
also enable you to administratively manage the alarm list (for example, deleting alarms).
The following administrative alarm states are available:
 None
 Acknowledged
 Observation
 Investigation
 Closed

Compliance Reporting
This topic describes the reporting capabilities of Cisco NSO.
Compliance Reporting
Report
 Used to check if configuration is definition Report
correct (compliant)
 Problem management requires
analysis of incident history
 Compliance reports can be used to
gather information Cisco NSO
 Design reports
 Reports can be designed upfront  Generate reports
 Reports can be generated when
needed
Compliance reporting
When the unexpected happens or things come to the worst and the network configuration is broken, there is a
need to gather information and verify the configuration. Cisco NSO has numerous functions to show
different aspects of such a network config verification. However, to simplify this task, the compliance
reporting can assemble information using a selection of these functions and present the resulting information
in one report. The aim for this report is to answer two fundamental questions:
 Who has done what?
 Is the network correctly configured?
What defines then a correctly configured network? Where is the master? NSO by nature, with the
configurations stored in Configuration Database (CDB), is the master. Checking the live devices against the
NSO stored device configuration is a fundamental part of compliance reporting. But it does not stop here.
Compliance reporting can also be based on one or a number of stored device templates which the live
devices are compared against. The compliance reports can also be a combination of both approaches.
Compliance verification can be defined to check the current situation or checking historic events, or both. To
assemble historic events, rollback files and audit logs are used. Therefore these functionalities must have
been enabled for the time period of interest, or else no history view can be presented.
The reports can be formatted either as text, html or docbook xml format. The intention of the docbook
format is that the user can take the report and by further post-processing create reports formatted by own
choice, for instance Portable Document Format (PDF) using Apache FOP.
Report Definition Options
Device selection options: Service selection options:
 all- devices: check all defined devices  all- services: check all defined services
 device- group: specified list of device groups  service: specified list of services
 device: specified list of devices  select- services: specified by an XPath
expression
 select- devices: specified by an XPath
expression
Device verification options: Service verification options:

 current out of sync  current out of sync
 historic changes  historic out of sync
 historic out of sync
The report has a device-check and a service-check container for specifying devices and services to check. The
compare-template list allows for specifying templates to compare device configurations against.
Devices can be defined in one of four different ways:

 all-devices: Check all defined devices
 device-group: Specified list of device groups
 device: Specified list of devices
 select-devices: Specified by an XPath expression
For a report definition specifying the device-check container, the default behavior for the verification of
devices is the following:
 To request a check-sync action to verify that the device is currently in sync. This behavior is controlled
by the leaf current-out-of-sync (default true).
 To scan history (i.e. logs) for failed check-sync events and report these. This behavior is controlled by
the leaf historic-out-of-sync (default true).
 To scan commit log (i.e. rollback files) for changes on the devices report these. This behavior is
controlled by the leaf historic-changes (default true).
Services can be defined in one of three ways:

 all-services - Check all defined services
 service - Specified list of services
 select-services - Specified by an XPath expression
For a report definition specifying the service-check container, the default behavior for the verification of
services is the following:

 To request a check-sync action to verify that the service is currently in sync. This behavior is controlled by
the leaf current-out-of-sync (default true).
 To scan history (i.e. logs) for failed check-sync events and report these. This behavior is controlled by the
leaf historic-out-of-sync (default true).
Compliance Reporting: Report Definitions via CLI
Create report definition
admin@ncs(config)# compliance reports report "Full PE Report"
admin@ncs(config-report-Full PE Report)# device-check device-group CSR-PE
admin@ncs(config-report-Full PE Report)# service-check all-services
admin@ncs(config-report-Full PE Report)# commit
Run report
admin@ncs# compliance reports report "Full PE Report" run
id 57
compliance-status violations
info Checking 5 devices and 6 services
location http://localhost:8080/compliance-reports/report_57_administrator_1_2014-11-
14T9:32:29:0.xml
admin@ncs#
The figure illustrates how the same can be accomplished using the NSO CLI.
Alternatively, if you use the Juniper style CLI you would do something like this:
administrator@ncs% set compliance reports report "Full PE
Report" device-check device-group CSR-PE
[ok][2014-11-14 09:17:01]
[edit]
administrator@ncs%
administrator@ncs% set compliance reports report "Full PE
Report" service-check all-services
[ok][2014-11-14 09:17:12]
[edit]
administrator@ncs% commit
Commit complete.
[ok][2014-11-14 09:17:48]
[edit]
administrator@ncs> request compliance reports report "Full PE
Report" run
id 58
compliance-status violations
info Checking 5 devices and 6 services
location http://localhost:8080/compliance-
reports/report_58_administrator_1_2014-11-14T9:29:2:0.xml
[ok][2014-11-14 09:29:05]
administrator@ncs> show compliance report-results report
COMPLIANCE
ID NAME TITLE TIME WHO
STATUS LOCATION

----------------------------------------------------------------
----------------------------------------------------------------
----------------------------------------------------
…
58 Full PE Report 2014-11-14T09:29:02+00:00
administrator violations http://localhost:8080/compliance-
reports/report_58_administrator_1_2014-11-14T9:29:2:0.xml
[ok][2014-11-14 09:29:54]
administrator@ncs>
Configuration Compliance Report
Device group name
 Ensure devices have standard configurations
based on device templates: Template name
admin@ncs(config)# compliance reports report CC_PE
admin@ncs(config-report-CC_PE)# compare-template "Template for PE Routers" "PE Routers"
admin@ncs(config-compare-template-Template for PE Routers/PE Routers)# commit
 Run the report:

admin@ncs# compliance reports report CC_PE run outformat html Template for IOS PE Routers
Device PE11
id 331
compliance-status violations config {
ios:ntp {
info Checking 2 devices and no services server {
location http://localhost:8080/compliance- ip {
+ peer- list 10.1.1.1 {
reports/report_3_admin_1_2016-1-6T0:0:39:0.html + }
admin@ncs# }
}
}
}
 View the report Device PE12
...
The last example of compliance reporting focuses on ensuring that a group of devices complies with standard
configuration sets defined by device templates. The printout on the right shows that PE11 is missing the
required NTP configuration.

Summary
 Alarms represent significant events that require action
 When integrating Cisco NSO with other systems it is important to consider how alarms will
be managed
 SNMP is typically used to retrieve alarms
 Custom alarm management can be used to create or process alarms
 Reports can be used to ensure that devices comply with the expected state (compare against
templates) and that services are compliant with the master configuration (on NSO)
References

NSO20 StudentGuide PDF

Uploaded by

Copyright:

Available Formats

NSO20 StudentGuide PDF

Uploaded by

Document Information

Original Title

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

NSO20 StudentGuide PDF

Uploaded by

Copyright:

Available Formats

NSO

Cisco Network Services

Start Using Cisco NSO.…………...…………………………......2-0

System Administration and Integration……………………..….4-0

 Network operators and service

 SDN and NFV address these challenges

© 2016 Cisco Systems, Inc. Cisco NSO Overview 1-3

Network Management Challenges

 We are configuring individual devices

© 2016 Cisco Systems, Inc. Cisco NSO Overview 1-5

© 2016 Cisco Systems, Inc. Cisco NSO Overview 1-7

Configuration changes (CLI)

© 2016 Cisco Systems, Inc. Cisco NSO Overview 1-9

 NETCONF as preferred device management YANG

The two primary components of Cisco NSO are:

Faster Service Deployment

 Rapid deployment of provisioning and configuration management systems

© 2016 Cisco Systems, Inc. Cisco NSO Overview 1-11

 Faster introduction and activation of new services

 Result: high cost and complexity

© 2016 Cisco Systems, Inc. Cisco NSO Overview 1-13

 Result: reduction in cost and

© 2016 Cisco Systems, Inc. Cisco NSO Overview 1-15

CAPEX OPEX is often 45% of OPEX

Source: Nokia Solutions

Orchestration Use Cases Using Cisco NSO

 Transport services (e.g. L2 & L3 MPLS VPNs)

© 2016 Cisco Systems, Inc. Cisco NSO Overview 1-17

Cisco NFV Orchestrator

Cisco 3rd Party VNF Manager

 Network-wide end-to-end configuration of VPN service (L3, L2, VPLS)

© 2016 Cisco Systems, Inc. Cisco NSO Overview 1-19

Web Cisco Day-0

 Simplified service instance deployment including zero-touch provisioning

 NFV Service Packages consisting of a number of selected VNFs

© 2016 Cisco Systems, Inc. Cisco NSO Overview 1-21

 New device registers with Day-0 server

 NSO deploys service by configuring physical and virtual devices

© 2016 Cisco Systems, Inc. Cisco NSO Overview 1-23

The figure illustrates different levels of access to the solution:

 VNF lifecycle management VNF Recovery and

 VM and service monitoring, recovery

© 2016 Cisco Systems, Inc. Cisco NSO Overview 1-25

OpenStack NETCONF, CLI, REST, ...

© 2016 Cisco Systems, Inc. Cisco NSO Overview 1-27

Service Custom Script

Predefined Action Predefined Action

Custom Script Custom Script

VNF Creation VNF Automated Management

 Rules control ESC behavior

© 2016 Cisco Systems, Inc. Cisco NSO Overview 1-29

Example: Quantum Virtual Packet Core (QvPC)

QvPC SI Configure VM VNF Manager

 Single or distributed instances of packet core elements Compute, Virtual or

© 2016 Cisco Systems, Inc. Cisco NSO Overview 1-31

 Dynamic network resource management

© 2016 Cisco Systems, Inc. Cisco NSO Overview 1-33

Cisco NSO Architecture

The Power of Abstractions