Sandbox Guide

Cisco dCloud

Cisco Network Services Orchestrator

5.2.1 v1

Created in Partnership with Solutions Readiness Engineers.

Last Updated: 13 December 2019

About This Sandbox

This guide for the preconfigured Cisco® Network Services Orchestrator 5.2.1 v1 sandbox includes:

About This Sandbox

Requirements

About This Solution

Topology

Get Started

Scenario 1. Connect to NSO Server

Scenario 2. Use Eclipse for YANG

Scenario 3. Explore NETCONF Device Example

Appendix A. Readme File Example

What’s Next?

© 2019 Cisco and/or its affiliates. All rights reserved. This document is Cisco Public Information. Page 1 of 22
Sandbox Guide
Cisco dCloud

Requirements
The table below outlines the requirements for this preconfigured sandbox.

Table 1. Requirements

Required Optional
Laptop Cisco AnyConnect®

About This Solution

Advanced networking applications are complex to provision, often requiring changes to multiple devices and large numbers of
parameters per device. Often, administrators make distributed changes in lockstep, because the failure of a single change can
disrupt service and be difficult to diagnose and fix.

This sandbox provides you with basic information to get started in the NSO sandbox. For more information about NSO, refer to
Network Services Orchestrator Solutions. Also explore the following NSO documents bookmarked in the browser in the
demonstration workstation:

• NSO Getting Started Guide

• NSO Installation Guide

• NSO User Guide

This sandbox features a ready-to-use NSO environment to test NSO installation and pre-packaged NSO examples. It also enables
you to run your own NSO applications.

This sandbox provides the following features:

• NSO: A single, network-wide interface to all network devices and all network applications and services.

• Service Orchestration: NSO orchestrates the lifecycle of network related service: development, deployment, and activation.
Create, modify, repair, and delete services on-demand.

• NFV Orchestration: Orchestrate the lifecycle of a virtual service - create, modify, repair and delete virtualized services on
customer demand, within minutes or seconds. Manage and configure the Virtual Network Function (VNF) that makes up the
virtual service and how they are chained together. Control a VNF Manager such as Cisco Elastic Services Controller (ESC)
and Virtual Infrastructure Managers (VIMs) including OpenStack and vSphere with the NFV Orchestrator (NFVO) NSO
Package.

• Device Management: Network device turn up, configuration, and capability management is handled by an NSO onboard
device manager. This reduces manual efforts to manage network elements and lowers risk of errors. Cisco and third-party
physical or virtual devices are managed through the device abstraction layer using NEDs (Network Element Drivers).

• Configuration Audit, Network Policy Compliance: NSO ensures the network is correctly configured and device
configurations conform to network-wide rules. Utilizing templates matching “golden configs” for various device types and roles,
NSO audits a device’s most recent running config against corresponding template – any deviations are flagged for correction.

© 2019 Cisco and/or its affiliates. All rights reserved. This document is Cisco Public Information. Page 2 of 22
Sandbox Guide
Cisco dCloud

Topology
This content includes preconfigured users and components to illustrate the scripted scenarios and features of the solution. Most
components are fully configurable with predefined administrative user accounts. You can see the IP address and user account
credentials to use to access a component by clicking the component icon in the Topology menu of your active session and in the
scenario steps that require their use.

Figure 1. dCloud Topology

Table 2. Component Details

Component Description

Network Services NSO Version 5.2.1

Orchestrator
Ubuntu OS Ubuntu Version 16.04

Java Java 8 JDK

Eclipse Luna Integrated Development Environment (with YANG plug-in)

YANG IDE plugin is used for VI (vim) editor

© 2019 Cisco and/or its affiliates. All rights reserved. This document is Cisco Public Information. Page 3 of 22
Sandbox Guide
Cisco dCloud

Get Started

Follow the steps to schedule a session of the content and configure your presentation environment.

1. Initiate your dCloud session. [Show Me How]

NOTE: It may take up to 10 minutes for your session to become active.

2. For best performance, connect to the workstation with Cisco AnyConnect VPN [Show Me How] and the local RDP client on
your laptop [Show Me How]

• Workstation 1: 198.18.133.252, Username: administrator, Password: C1sco12345.

3. Wait until all stages of the Launch Progress bar turn green before proceeding.

© 2019 Cisco and/or its affiliates. All rights reserved. This document is Cisco Public Information. Page 4 of 22
Sandbox Guide
Cisco dCloud

Scenario 1. Connect to NSO Server

VALUE PROPOSTION:

This scenario demonstrates how to connect to the NSO server. The documentation found on the workstation desktop in the NSO
Docs folder describes the installation process. For more information, refer to the NSO 5.2.1 Documentation Overview and the NSO
Installation Guide.

Steps

1. From the workstation desktop, double-click the NSO Host PuTTY icon to automatically log in to the NSO server as cisco.

2. Enter ls to verify that the NSO installation binary (nso-5.2.1.linux.x86_64.installer.bin) appears in the home directory.

© 2019 Cisco and/or its affiliates. All rights reserved. This document is Cisco Public Information. Page 5 of 22
Sandbox Guide
Cisco dCloud

Install NSO Application

1. Enter the following command to install NSO:

sh nso-5.2.1.linux.x86_64.installer.bin $HOME/nso-5.2.1 --local-install

2. Enter the following command to load the NSO environment:

echo "source $HOME/nso-5.2.1/ncsrc" >> .profile

NOTE: NSO requires certain environmental variables to run. These variables are included in the ncsrc file located in the
installation folder. Running the command above includes them in your profile file for future sessions.

3. Click X (at top right of terminal window) and click OK in the confirmation pop-up to close the PuTTY terminal.

© 2019 Cisco and/or its affiliates. All rights reserved. This document is Cisco Public Information. Page 6 of 22
Sandbox Guide
Cisco dCloud

4. Double-click the NSO Host PuTTY icon to open a new PuTTY terminal and allow the environment to load.

NOTE: As an alternative to closing the PuTTY terminal and opening a new one, enter source $HOME/nso-5.2.1/ncsrc. If
you do this, however, you must enter the command at every login.

5. Before starting NCS, complete the following steps to create a database for your project. Enter the following command to
create a work directory:
mkdir ncs-run

6. Enter the following command to run the setup program:

ncs-setup --dest $HOME/ncs-run

7. Enter the following commands to move to the new directory and start NCS:
cd ncs-run
ncs

NOTE: It takes less than a minute for NCS to start.

8. Enter the following command to stop NCS and return to the $HOME directory:
ncs --stop
cd

Test NSO Pre-Packaged Examples

1. Enter the following command to create a working directory to store your sandboxes:
mkdir myprojects

2. Enter the following command to copy the pre-packaged NSO examples to your working directory:
cp -r $HOME/nso-5.2.1/examples.ncs/* myprojects/

NOTE: You now can explore the pre-package examples. Each example includes a README file that contains instructions. To
work on each example, you must navigate to the appropriate directory.

3. Enter the following command to change the directory to the example directory:
cd myprojects/

NOTE: The myprojects folder is the location to which you copied the pre-package NSO examples.

4. Enter ls to view the contents of this directory.

© 2019 Cisco and/or its affiliates. All rights reserved. This document is Cisco Public Information. Page 7 of 22
Sandbox Guide
Cisco dCloud

5. Enter the following commands to view the contents of the 0-hello-world directory:
cd getting-started/using-ncs/0-hello-world/
ls

NOTE: The README file in the 0-hello-world directory is an example guide that walks users through the initial steps for
using the NSO application.

6. Enter more README.

7. Close the PuTTY terminal session. Refer to Appendix A for the complete contents of the README file.

Explore Additional Examples

There are other examples available in the myprojects directory about how to use NSO. Cisco recommends launching the NSO
Host PuTTY session and exploring the examples in the following order (with increasing difficulty). Refer to the previous procedure
for instructions.

1. myprojects/getting-started/using-ncs/0-hello-world/

2. myprojects/getting-started/using-ncs/4-netconf-device

3. myprojects/getting-started/using-ncs/1-simulated-cisco-ios/

4. myprojects/datacenter/datacenter

© 2019 Cisco and/or its affiliates. All rights reserved. This document is Cisco Public Information. Page 8 of 22
Sandbox Guide
Cisco dCloud

5. myprojects/service-provider/simple-mpls-vpn

IMPORTANT: This is a sandbox environment. This guide provides a walk-through of the initial NSO installation. It also
directs you to example guides, created by program developers, about how to use the application.

Run Your Own NSO Application

Within your working environment, you can create your own NSO applications and services. Create a new blank folder and re-use
as much as possible from the existing examples.

Additional Tools

This sandbox includes the following additional tools:

• VI editor YANG plugin: Used to create and edit YANG models in the NSO server

• Eclipse IDE: Used as a graphical IDE to create and edit JAVA code or YANG models

• Postman REST client: Used to test the NSO REST API

This concludes scenario 1.

© 2019 Cisco and/or its affiliates. All rights reserved. This document is Cisco Public Information. Page 9 of 22
Sandbox Guide
Cisco dCloud

Scenario 2. Use Eclipse for YANG

VALUE PROPOSTION:

This scenario demonstrates how to open YANG files by using the Eclipse editor.

If your laptop has an X11 server, you can launch Eclipse through SSH by entering the following:
ssh -X cisco@198.18.134.28
$ /opt/eclipse/eclipse

However, this document assumes you connect to the workstation by using RDP.

Steps

1. On the workstation desktop, double-click the Eclipse.xlaunch icon.

NOTE: It may take a few seconds to start Eclipse.

2. Close the Eclipse welcome screen by clicking on the X on the top left of the screen.

© 2019 Cisco and/or its affiliates. All rights reserved. This document is Cisco Public Information. Page 10 of 22
Sandbox Guide
Cisco dCloud

3. Click File > New > Project.

4. In the New Project dialog box, select General > Project and click Next.

© 2019 Cisco and/or its affiliates. All rights reserved. This document is Cisco Public Information. Page 11 of 22
Sandbox Guide
Cisco dCloud

5. Enter my_project in the Project Name field and click Finish.

6. Select the my_project folder.

© 2019 Cisco and/or its affiliates. All rights reserved. This document is Cisco Public Information. Page 12 of 22
Sandbox Guide
Cisco dCloud

7. Click File > Import.

8. From the Import screen, select General > File System and click Next.

© 2019 Cisco and/or its affiliates. All rights reserved. This document is Cisco Public Information. Page 13 of 22
Sandbox Guide
Cisco dCloud

9. Click Browse.

10. Select Cisco from the Places pane. Then select myprojects and click OK.

© 2019 Cisco and/or its affiliates. All rights reserved. This document is Cisco Public Information. Page 14 of 22
Sandbox Guide
Cisco dCloud

11. In the left-hand pane of the Import dialog box, click the right arrow to expand and navigate to the following directories:
myprojects > getting-started > using-ncs > 4-netconf-device.

NOTE: Eclipse may be sensitive to your double-clicking speed, you may need to click faster.

12. Check only the host.yang checkbox and click Finish.

© 2019 Cisco and/or its affiliates. All rights reserved. This document is Cisco Public Information. Page 15 of 22
Sandbox Guide
Cisco dCloud

13. From the Package Explorer pane, expand my_project > getting-started > using-ncs > 4-netconf-device and double-click
host.yang.

NOTE: Examine the host.yang file, but do not make any changes to it because the file is used in the next scenario.

This concludes scenario 2.

© 2019 Cisco and/or its affiliates. All rights reserved. This document is Cisco Public Information. Page 16 of 22
Sandbox Guide
Cisco dCloud

Scenario 3. Explore NETCONF Device Example

VALUE PROPOSTION:

This scenario demonstrates the NETCONF device example.

Steps

1. Close any previously opened NSO Host PuTTY sessions.

2. Double-click the NSO Host PuTTY icon to open a new PuTTY terminal.

3. Enter the following command:

cd myprojects/getting-started/using-ncs/4-netconf-device

4. Enter the following command to create a package called host.

NOTE: There must be a space before and after the dot (.) in the following command.

ncs-make-package --netconf-ned . host

5. Enter the following command to build the package (including the parenthesis):
( cd host/src && make )

6. In the output, verify that the build succeeded.

© 2019 Cisco and/or its affiliates. All rights reserved. This document is Cisco Public Information. Page 17 of 22
Sandbox Guide
Cisco dCloud

7. Enter the following command to create two simulated netsim devices. This command forces the device names to start with the
letter h.
ncs-netsim create-network host 2 h

8. Enter the following command to enable NCS to run out of the directory:
ncs-setup --dest .

9. Enter the following command to start the netsim devices:

ncs-netsim start

10. Enter ncs to start NCS.

ncs

11. Enter the following commands to connect to ncs-admin:

ncs_cli -u admin

12. Enter the following command to show packages:

show packages

© 2019 Cisco and/or its affiliates. All rights reserved. This document is Cisco Public Information. Page 18 of 22
Sandbox Guide
Cisco dCloud

13. Enter the following command to read the configuration from the devices:
request devices sync-from

14. Enter the following commands to clean up your session by first exiting the admin-cli and then stopping ncs and netsim:
exit
ncs --stop
ncs-netsim stop

This concludes scenario 3.

© 2019 Cisco and/or its affiliates. All rights reserved. This document is Cisco Public Information. Page 19 of 22
Sandbox Guide
Cisco dCloud

Appendix A. Readme File Example

This is the contents of the file /home/cisco/myprojects/getting-started/using-ncs/0-hello-world/README.

File Contents
Hello World
-----------

The purpose of this example is to start NCS, understand the different

directories and files NCS uses. As well as starting the NCS CLI, and
Web UI.

Preparations
------------
1) Make sure you have sourced the ncsrc file in $NCS_DIR. This sets up paths and
environment variables in order to run NCS. So this must be done all times
before running NCS, so it is recommended to put that in your profile.

Optional:
If you do not want to create the example files in the NCS installation
directory $NCS_DIR/examples.ncs/getting-started/using-ncs/0-hello-world,
for example if you are several users sharing the same installation, you can
run the example in a separate directory.

2) Create an empty directory, for example in your home directory. NCS and the
simulator will create files and directories in this example. Make sure you
change to this directory before continuing.

NCS 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 NCS daemon will look for ./ncs.conf, followed by
etc/ncs/ncs.conf in the NCS installation directory. In order to make
it easy to get started NCS 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).

$ ls

$ ncs-setup --dest .
$ ls
README.ncs ncs-cdb/ packages/
logs/ ncs.conf state/ scripts/

An initial configuration file, ./ncs.conf and the directories need to

run NCS were created. Now, to start the NCS daemon run "ncs"
(optionally providing the configuration file as argument: -c
./ncs.conf)

$ ncs

The NCS 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

© 2019 Cisco and/or its affiliates. All rights reserved. This document is Cisco Public Information. Page 20 of 22
Sandbox Guide
Cisco dCloud

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

By default NCS also starts it's built-in SSH server, listening on port
2024. So ssh can also be used to log into the CLI:

$ ssh -l admin -p 2024 localhost

admin@localhost's password:

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.

NCS also starts a web-server, listening on port 8080. By directing a

browser to http://localhost:8080/ you can login using the Web UI with
user admin again.

stop the NCS daemon use the --stop option:

$ ncs --stop

NCS 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 NCS, and to revert
to the "empty" factory default configuration, use the --reset option
to ncs-setup.

$ ncs-setup --reset

Further reading
---------------

Man-pages: ncs-setup(1) ncs(1) ncs_cli(1)

© 2019 Cisco and/or its affiliates. All rights reserved. This document is Cisco Public Information. Page 21 of 22
Sandbox Guide
Cisco dCloud

What’s Next?
Check out these related demos on Cisco dCloud!

• Cisco Network Services Orchestrator 4.7.1 L3VPN v1

• Cisco WAN Automation Engine 7.1.2 - Segment Routing and XTC Sandbox v1

• Cisco Network Services Orchestrator - Automated Deployments with Zero-Touch Provisioning v2

© 2019 Cisco and/or its affiliates. All rights reserved. This document is Cisco Public Information. Page 22 of 22