Running The NSO Examples

Overview

This section provides an overview of how to run the examples provided by the NSO installer. By working through the examples, the reader should get a good overview of the various aspects of NSO and hands-on experience from interacting with it.

This section references the examples located in $NCS_DIR/examples.ncs. The examples all have README files that includes instructions related to the example.

General Instructions

Make sure NSO is installed according to the instructions in "Installing NSO". Source the ncsrc file in the NSO installation directory to setup the local environment. For example:

$ source /opt/ncs/ncsrc

Then proceed to the example directory:

$ cd $NCS_DIR/examples.ncs/getting-started/using-ncs/1-simulated-cisco-ios

Then follow the instructions in the README files that are located in the example directories.

Every example directory is a complete NSO run-time directory. The README file and the detailed instructions later in this guide show how to generate a simulated network and NSO configuration for running the specific examples. Basically, the following steps are done:

Create a simulated network using the ncs-netsim --create-network command:
```
$ ncs-netsim create-network cisco-ios-cli-3.8 3 ios
```
This creates 3 Cisco IOS devices called ios0, ios1, and ios2.
Create an NSO run-time environment using the ncs-setup command:
```
$ ncs-setup --dest .
```
This command uses the --dest option to create local directories for logs, database files, and the NSO configuration file to the current directory (note that '.' refers to the current directory).
Start ncs-netsim:
```
$ ncs-netsim start
```
Start NSO:
```
$ ncs
```

It is important to make sure that you stop ncs and ncs-netsim when moving between examples using the stop option of the netsim and the --stop option of the ncs.

$ cd $NCS_DIR/examples.ncs/getting-started/1-simulated-cisco-ios
$ ncs-netsim start
$ ncs
$ ncs-netsim stop
$ ncs --stop

Common Mistakes

The three most common mistakes are:

You have not sourced the ncsrc file:
```
$ ncs
-bash: ncs: command not found
```
You are trying to start NSO from a directory, which is not setup as a runtime directory.
```
$ ncs
Bad configuration: /etc/ncs/ncs.conf:0: "./state/packages-in-use: \
   Failed to create symlink: no such file or directory"
Daemon died status=21
```
What happens above is that NSO did not find a ncs.conf in the local directory so it uses the default in /etc/ncs/ncs.conf. That ncs.conf says there shall be directories at ./ such as ./state which is not true.

Make sure you cd to the "root" of the example and check that there is a ncs.conf file, and a cdb-dir directory.
You already have another instance of NSO running (or same with netsim):
```
$ ncs
Cannot bind to internal socket 127.0.0.1:4569 : address already in use
Daemon died status=20
$ ncs-netsim start
DEVICE c0 Cannot bind to internal socket 127.0.0.1:5010 : \
  address already in use
Daemon died status=20
FAIL
```
In order to resolve the above, just stop the running instance of NSO and netsim. And remember that it does not matter where you started the running NSO and netsim, there is no need to cd back to the other example before stopping.

Another problem that users run into sometimes is where the netsim device configuration are not loaded into NSO. This can happen if the order of commands are not followed. To resolve, remove the database files in the ncs_cdb directory (keep any files with .xml extension). In this way NSO will reload the XML initialization files provided by ncs-setup.

$ ncs --stop
$ cd ncs-cdb/
$ ls
A.cdb
C.cdb
O.cdb
S.cdb
netsim_devices_init.xml
$ rm *.cdb
$ ncs